Authentication API

Sessions, multi-factor authentication and step-up re-authentication for humans.

These endpoints authenticate people, not agents. An agent never logs in; it proves possession of a private key at the gateway. Signup creates an organization and its first owner in one transaction, so there is no window in which an organization exists without an administrator.

#Endpoints

	Endpoint	Permission	Notes
`POST`	`/v1/auth/signup`	none	—
`POST`	`/v1/auth/signup/start`	none	—
`POST`	`/v1/auth/signup/verify`	none	—
`GET`	`/v1/onboarding`	none	—
`PUT`	`/v1/onboarding/steps/:step`	none	—
`POST`	`/v1/onboarding/complete`	none	—
`POST`	`/v1/auth/login`	none	—
`POST`	`/v1/auth/mfa/verify`	none	—
`POST`	`/v1/auth/step-up`	none	—
`GET`	`/v1/auth/session`	none	—
`POST`	`/v1/auth/logout`	none	—
`POST`	`/v1/auth/cli/start`	none	—
`POST`	`/v1/auth/cli/token`	none	—
`GET`	`/v1/auth/cli/requests/{requestId}`	none	—
`GET`	`/v1/auth/cli/requests`	none	—
`POST`	`/v1/auth/cli/requests/{requestId}/approve`	none	—
`POST`	`/v1/auth/cli/requests/{requestId}/deny`	none	—

#What each endpoint does

#`POST /v1/auth/signup`

Create an organization and the first owner.

Requires no console permission.

Request body:

json
{
  "email": "string",
  "password": "string",
  "name": "string",
  "organizationName": "string"
}

#`POST /v1/auth/signup/start`

Start an e-mail sign-up: e-mails a six-digit code. Nothing is created yet.

Requires no console permission.

Request body:

json
{
  "name": "string",
  "email": "string",
  "password": "string"
}

#`POST /v1/auth/signup/verify`

Verify the e-mailed code; creates the organization, the owner and a session.

Requires no console permission.

Request body:

json
{
  "email": "string",
  "code": "string"
}

#`GET /v1/onboarding`

The signed-in person’s onboarding progress, answers and setup details.

Requires no console permission.

#`PUT /v1/onboarding/steps/:step`

Save one onboarding step (profile, goals, frameworks, mode, connect).

Requires no console permission.

#`POST /v1/onboarding/complete`

Finish onboarding; applies the starting mode to the chosen environment.

Requires no console permission.

Request body:

json
{
  "environment_id": "string?"
}

#`POST /v1/auth/login`

Authenticate with email and password.

Requires no console permission.

Request body:

json
{
  "email": "string",
  "password": "string"
}

#`POST /v1/auth/mfa/verify`

Complete MFA and receive a session.

Requires no console permission.

Request body:

json
{
  "mfa_challenge": "string",
  "code": "string"
}

#`POST /v1/auth/step-up`

Re-authenticate for a high-impact operation.

Requires no console permission.

Request body:

json
{
  "password": "string?",
  "code": "string?"
}

#`GET /v1/auth/session`

Current session, scope and effective permissions.

Requires no console permission.

#`POST /v1/auth/logout`

Revoke the current session.

Requires no console permission.

#`POST /v1/auth/cli/start`

Open a browser sign-in request for the CLI (PKCE S256).

Requires no console permission.

Request body:

json
{
  "flow": "LOOPBACK | DEVICE",
  "code_challenge": "string",
  "redirect_port": "number?",
  "client": "{ hostname?, platform?, version? }"
}

#`POST /v1/auth/cli/token`

Redeem an approved CLI sign-in for a session.

Requires no console permission.

Request body:

json
{
  "request_id": "string",
  "code_verifier": "string",
  "code": "string?"
}

#`GET /v1/auth/cli/requests/{requestId}`

Show a pending CLI sign-in request for approval.

Requires no console permission.

#`GET /v1/auth/cli/requests`

Find a pending device sign-in request by its user code.

Requires no console permission.

#`POST /v1/auth/cli/requests/{requestId}/approve`

Approve a CLI sign-in as the signed-in person.

Requires no console permission.

Request body:

json
{
  "user_code": "string"
}

#`POST /v1/auth/cli/requests/{requestId}/deny`

Refuse a CLI sign-in request.

Requires no console permission.