---
title: "Authentication API"
description: "Sessions, multi-factor authentication and step-up re-authentication for humans."
label: "Authentication"
generated: "the API catalogue in apps/control-plane/src/routes/developer.ts"
---


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.