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.

Body

application/json

emailstringrequired

maxLength: 254

passwordstringrequired

maxLength: 512

transportstring

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

one of: cookie, bearerdefault: "cookie"

Responses

errors: application/problem+json

200

401

Unauthorized

403

Forbidden

422

Unprocessable Entity

429

Too Many Requests

500

Internal Server Error

503

Service Unavailable

Match errors on the problem's code, which stays the same, not on its message.

Send a request

Server

Body

The request goes from your browser straight to this server; nothing passes through this site. The API must allow this site's origin for CORS.

Requestexample

curl -X POST "$API_URL/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "password": "string",
  "transport": "cookie"
}'

body := strings.NewReader(`{
  "email": "ada@example.com",
  "password": "string",
  "transport": "cookie"
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost,
	apiURL + "/v1/auth/login", body)
if err != nil {
	return err
}
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
	return err
}
defer res.Body.Close()

const res = await fetch(`${apiUrl}/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();

Responseexample

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

{
  "code": "string",
  "status": 401,
  "title": "Unauthorized",
  "detail": "string",
  "request_id": "req_9f86d081884c7d65",
  "type": "string"
}

{
  "code": "string",
  "status": 403,
  "title": "Forbidden",
  "detail": "string",
  "request_id": "req_9f86d081884c7d65",
  "type": "string"
}

{
  "code": "string",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "string",
  "errors": [
    {
      "message": "expected length >= 1",
      "location": "body.name"
    }
  ],
  "request_id": "req_9f86d081884c7d65",
  "type": "string"
}

{
  "code": "string",
  "status": 429,
  "title": "Too Many Requests",
  "detail": "string",
  "request_id": "req_9f86d081884c7d65",
  "type": "string"
}