API reference

Base path: /api

Most routes need the project-id header. Authenticated routes also need Authorization: Bearer <access_token>.

Endpoint list

Common headers

Token response

Successful signup (when tokens are issued), login, and refresh return:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_at": "2026-08-04T12:15:00.000000Z",
  "refresh_token": "...",
  "refresh_token_expires_at": "2026-09-03T12:00:00.000000Z",
  "user": {
    "id": 1,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "email": "[email protected]",
    "display_name": "Ada",
    "email_verified_at": null,
    "metadata": {}
  }
}

Signup

[POST] /auth/signup

Body

Responses

• 201 — tokens issued
• 202 — email verification required

{
  "message": "Email verification required.",
  "code": "email_verification_required",
  "verification_required": true,
  "user": {
    "id": 1,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "email": "[email protected]",
    "display_name": "Ada",
    "email_verified_at": null,
    "metadata": {}
  }
}

Example

curl -X POST https://your-domain.com/api/auth/signup \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "project-id: YOUR_PROJECT_UUID" \
  -d '{"email":"[email protected]","password":"secret-password","display_name":"Ada"}'

Login

[POST] /auth/login

Body

Responses

• 200 — token response
• 401 — invalid credentials
• 403 — email verification required
• 429 — lockout after failed attempts (retry_after seconds)

Example

curl -X POST https://your-domain.com/api/auth/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "project-id: YOUR_PROJECT_UUID" \
  -d '{"email":"[email protected]","password":"secret-password"}'

Refresh

[POST] /auth/refresh

Body

Responses

• 200 — new token response
• 401 — invalid refresh token
• 403 — email verification required

Logout

[POST] /auth/logout

Requires access token. Revokes the current session.

Logout all

[POST] /auth/logout-all

Requires access token. Revokes every session for the user.

Me

[GET] /auth/me

Requires access token.

{
  "user": {
    "id": 1,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "email": "[email protected]",
    "display_name": "Ada",
    "email_verified_at": "2026-08-04T12:00:00.000000Z",
    "metadata": {}
  }
}

Change password

[POST] /auth/change-password

Body

Email verification

See Email verification for resend and confirm details.

User API keys

See User API keys for create, list, revoke, and introspect.

Webhooks

Authentication can emit events such as:

• auth.signup.success
• auth.login.success
• auth.logout.success
• auth.logout_all.success
• auth.email_verification.verified

Configure them under Webhooks.

Notes

• Responses do not include an abilities array.
• Social id_token exchange is not available in the current API.
• For CMS writes, use a BFF and a project API token.

Next

• SDK
• Concepts