API reference/Auth

Finish signing in with a second factor

POST/v1/auth/login/mfa

After a 202 from `POST /v1/auth/login`: send the challenge token with a code from the authenticator app, a recovery code, or a passkey's response (start it with `POST /v1/auth/login/mfa/passkey`). Each sign-in allows 5 attempts within 5 minutes; each code works once.

no auth

Request body application/json · required

challenge_tokenstringrequired

From the 202 response of POST /v1/auth/login

max length 256

codestring

A code from the authenticator app

max length 16

passkeyobject

ceremony_tokenstringrequired

From POST /v1/auth/login/mfa/passkey when signing in, or POST /v1/auth/passkeys/verification when signed in

max length 256

credentialobjectrequired

The PublicKeyCredential from navigator.credentials.get(), as JSON

recovery_codestring

A recovery code, instead of code

max length 32

transportstring

cookie (browsers): an HttpOnly session cookie; bearer (native apps): the token in the response

one of "cookie", "bearer" · default "cookie"

Responses

200OKapplication/json

mfaobject

challenge_tokenstringrequired

Send it to POST /v1/auth/login/mfa. It is shown once.

expires_atstring (date-time)required

methodsarray of stringrequired

Second factors accepted: totp (a code from the authenticator app), passkey or recovery_code

sessionobject

created_atstring (date-time)required

currentbooleanrequired

The session making this request

expires_atstring (date-time)required

When the session ends unless used again

idstringrequired

ipstring

last_seen_atstring (date-time)required

mfa_verifiedbooleanrequired

Signed in or confirmed with a second factor

user_agentstring

tokenstring

Only with transport bearer: send it as Authorization: Bearer <token>. It is shown once.

userobject

created_atstring (date-time)required

emailstringrequired

email_verifiedbooleanrequired

has_passwordbooleanrequired

The account has a password; accounts created with Google or Apple don't, until they reset one

idstringrequired

rolesarray of stringrequired

Platform roles, such as platform_admin

401Unauthorizedapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

422Unprocessable Entityapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

429Too Many Requestsapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

500Internal Server Errorapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

503Service Unavailableapplication/problem+json

codestringrequired

Stable machine-readable error code

detailstring

Human-readable explanation

errorsarray of object

Field-level validation errors

request_idstring

Correlates with server logs and traces

statusinteger (int64)required

HTTP status code

titlestringrequired

Short summary of the problem type

typestring

URI identifying the problem type

Was this page useful?

v0.5

Request

curl -X POST "https://api.example.com/v1/auth/login/mfa" \
  -H "Content-Type: application/json" \
  -d '{
  "challenge_token": "string",
  "code": "123456",
  "passkey": {
    "ceremony_token": "string",
    "credential": {}
  },
  "recovery_code": "abcde-fghij",
  "transport": "cookie"
}'

req, _ := http.NewRequest("POST", "https://api.example.com/v1/auth/login/mfa", strings.NewReader(`{
  "challenge_token": "string",
  "code": "123456",
  "passkey": {
    "ceremony_token": "string",
    "credential": {}
  },
  "recovery_code": "abcde-fghij",
  "transport": "cookie"
}`))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close()

const res = await fetch("https://api.example.com/v1/auth/login/mfa", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "challenge_token": "string",
    "code": "123456",
    "passkey": {
      "ceremony_token": "string",
      "credential": {}
    },
    "recovery_code": "abcde-fghij",
    "transport": "cookie"
  }),
});
const data = await res.json();

Response

{
  "mfa": {
    "challenge_token": "string",
    "expires_at": "2026-09-15T12:00:00Z",
    "methods": [
      "string"
    ]
  },
  "session": {
    "created_at": "2026-09-15T12:00:00Z",
    "current": true,
    "expires_at": "2026-09-15T12:00:00Z",
    "id": "ses_nbswy3dpeb3w64tmmq",
    "ip": "string",
    "last_seen_at": "2026-09-15T12:00:00Z",
    "mfa_verified": true,
    "user_agent": "string"
  },
  "token": "string",
  "user": {
    "created_at": "2026-09-15T12:00:00Z",
    "email": "ada@example.com",
    "email_verified": true,
    "has_password": true,
    "id": "usr_mfrggzdfmztwq2lk",
    "roles": [
      "string"
    ]
  }
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

{
  "code": "project_name_taken",
  "detail": "project name is already taken",
  "errors": [
    {
      "location": "body.name",
      "message": "expected length >= 1"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "status": 409,
  "title": "Conflict",
  "type": "string"
}

Base URL: https://api.example.com
Auth: none