API reference/Auth

Sign in

POST/v1/auth/login

Starts a session (200). Browsers get an HttpOnly `__Host-session` cookie; native apps pass `"transport": "bearer"` and get the token in the response. For an account with two-factor authentication the response is 202 with `mfa.challenge_token` instead: finish with `POST /v1/auth/login/mfa`.

no auth

Request body application/json · required

emailstringrequired

max length 254

passwordstringrequired

max length 512

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

403Forbiddenapplication/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" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "password": "string",
  "transport": "cookie"
}'

req, _ := http.NewRequest("POST", "https://api.example.com/v1/auth/login", strings.NewReader(`{
  "email": "ada@example.com",
  "password": "string",
  "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", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "email": "ada@example.com",
    "password": "string",
    "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"
}

{
  "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