---
title: Authentication Reference
path: reference/authentication
status: published
---

# Authentication Reference

All authentication endpoints. For the conceptual overview, see [Authentication](../02-getting-started/02-authentication.md).

**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](./11-error-codes.md) for the full list.

## Related

- [Authentication (concepts)](../02-getting-started/02-authentication.md)
- [Roles and Permissions](../03-core-concepts/02-roles-and-permissions.md)
- [Custom Roles (advanced)](../07-advanced/04-custom-roles.md)