Authentication Reference

All authentication endpoints. For the conceptual overview, see Authentication.

Base path: /v1/auth/

POST /v1/auth/identify#

Identify a user by email and return the tenants they can sign into.

bash
curl -X POST https://scaigrid.scailabs.ai/v1/auth/identify \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@acme.example"}'

Response:

json
{
  "status": "ok",
  "data": {
    "user_exists": true,
    "tenants": [
      {"id": "tenant_acme", "slug": "acme-corp", "display_name": "Acme Corp"},
      {"id": "tenant_partner", "slug": "partner-ws", "display_name": "Partner Workspace"}
    ]
  }
}

If the user has access to multiple tenants, they pick one for the subsequent authorize call. No authentication required on this endpoint.

POST /v1/auth/authorize#

Begin an OAuth 2.0 authorization code flow with PKCE.

bash
curl -X POST https://scaigrid.scailabs.ai/v1/auth/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acme.example",
    "tenant_id": "tenant_acme",
    "code_challenge": "<base64url-sha256 of verifier>",
    "code_challenge_method": "S256",
    "redirect_uri": "https://your-app.example/oauth/callback",
    "state": "opaque-csrf-token"
  }'

Response includes a URL to ScaiKey where the user completes SSO:

json
{
  "data": {
    "authorize_url": "https://scaikey.scailabs.ai/oauth/authorize?...",
    "flow_id": "flow_abc"
  }
}

GET /v1/auth/callback#

OAuth callback handler. ScaiKey redirects here with an authorization code. Exchanges for tokens and redirects to the caller's redirect_uri.

Usually called by a user's browser after SSO, not directly by application code.

POST /v1/auth/token#

Exchange an authorization code for access + refresh tokens.

bash
curl -X POST https://scaigrid.scailabs.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_xyz",
    "code_verifier": "<original PKCE verifier>",
    "redirect_uri": "https://your-app.example/oauth/callback"
  }'

Response:

json
{
  "data": {
    "access_token": "eyJhbGc...",
    "refresh_token": "ref_xyz...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "openid profile email"
  }
}

POST /v1/auth/refresh#

Exchange a refresh token for a fresh access token.

bash
curl -X POST https://scaigrid.scailabs.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "ref_xyz..."}'

Response identical to /token. Refresh tokens have their own (longer) lifetime — when they expire, the user must sign in again.

POST /v1/auth/logout#

Revoke the current session.

bash
curl -X POST https://scaigrid.scailabs.ai/v1/auth/logout \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content. Any subsequent request with the same token returns 401 AUTH_TOKEN_INVALID.

GET /v1/auth/me#

Get the current user's profile.

bash
curl https://scaigrid.scailabs.ai/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Response:

json
{
  "data": {
    "user_id": "user_abc",
    "email": "alice@acme.example",
    "name": "Alice Example",
    "display_name": "Alice",
    "tenant_id": "tenant_acme",
    "tenant_name": "Acme Corp",
    "partner_id": "partner_internal",
    "roles": ["tenant_admin"],
    "permissions": ["models:use", "users:manage", ...],
    "module_permissions": ["scaibot:bots:create", ...],
    "created_at": "2025-11-01T12:00:00Z"
  }
}

Equivalent to GET /v1/me.

Error codes#

Code	Meaning
`AUTH_TOKEN_MISSING`	No Authorization header
`AUTH_TOKEN_INVALID`	Token signature invalid or expired
`AUTH_INSUFFICIENT_SCOPE`	Token lacks a required scope
`AUTH_FLOW_INVALID`	OAuth flow state invalid or expired
`AUTH_IDENTITY_NOT_FOUND`	No account found for email
`SESSION_EXPIRED`	Token expired, refresh required

See Error Codes for the full list.

Authentication Reference

POST /v1/auth/identify#

POST /v1/auth/authorize#

GET /v1/auth/callback#

POST /v1/auth/token#

POST /v1/auth/refresh#

POST /v1/auth/logout#

GET /v1/auth/me#

Error codes#

Related#