POST /api/auth/magic/code - the code shown on the other device, typed into the waiting window here. Completes the sign-in on THIS browser (the one that asked).

POST

/api/auth/magic/code

curl --request POST \
  --url https://example.com/api/auth/magic/code \
  --header 'Content-Type: application/json' \
  --data '{ "code": "example" }'

Request Body^required

Media typeapplication/json

object

code

required

string

Example^generated

{
  "code": "example"
}

Responses

200

Session issued on the requesting device (or a 2FA interim)

Media typeapplication/json

object

csrf_token

required

string

expires_in

required

integer format: int64

user

required

object

email

string | null

id

required

string format: uuid

Example^generated

{
  "csrf_token": "example",
  "expires_in": 1,
  "user": {
    "email": "example",
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}

202

No session: the code was wrong or the request was refused

Media typeapplication/json

A code that did not sign this device in: wrong_code (with the attempts left) or refused (with the kernel’s reason slug). 202, never 4xx: the request was understood, the sign-in simply did not happen.

object

message

required

The server’s English wording; the client localises by outcome/reason.

string

outcome

required

wrong_code | refused

string

reason

wrong_device | no_code_issued | code_expired | too_many_attempts | already_completed | already_opened | invalidated | link_expired

string | null

remaining_attempts

integer | null format: int32

Example^generated

{
  "message": "example",
  "outcome": "example",
  "reason": "example",
  "remaining_attempts": 1
}

400

Structured client error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden license_required license_expired bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited too_many_requests quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}