API reference/Auth

Sign in with an Apple ID token

POST/v1/auth/apple/token

For iOS apps. Returns a session like `POST /v1/auth/login`, or 202 with a second-factor challenge.

no auth

Request body application/json · required

authorization_codestring

authorizationCode, exchanged for a refresh token revoked when the account is deleted

max length 4096

id_tokenstringrequired

identityToken from ASAuthorizationAppleIDCredential

max length 16384

namestring

fullName, which Apple gives only the first time

max length 200

noncestringrequired

From POST /v1/auth/apple/nonce, before hashing

max length 256

transportstring

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

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

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

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/apple/token" \
  -H "Content-Type: application/json" \
  -d '{
  "authorization_code": "string",
  "id_token": "string",
  "name": "string",
  "nonce": "string",
  "transport": "bearer"
}'

req, _ := http.NewRequest("POST", "https://api.example.com/v1/auth/apple/token", strings.NewReader(`{
  "authorization_code": "string",
  "id_token": "string",
  "name": "string",
  "nonce": "string",
  "transport": "bearer"
}`))
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/apple/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "authorization_code": "string",
    "id_token": "string",
    "name": "string",
    "nonce": "string",
    "transport": "bearer"
  }),
});
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