> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slate-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Obtain and use Bearer tokens for the Slate API.

The Slate API uses short-lived JWT access tokens with matching refresh tokens.

## Obtaining a token

Exchange staff credentials for a token pair:

```bash theme={null}
curl -X POST https://api.{your-broker-domain}/api/admin/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "staff@example.com",
    "password": "••••••••"
  }'
```

Response:

```json theme={null}
{
  "access_token":  "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "Ck9M5...",
  "token_type": "bearer",
  "expires_in": 900
}
```

For customer-facing applications, use `POST /api/customer/login` instead. The
response shape is the same.

## Using a token

Include the token on every authenticated request:

```bash theme={null}
curl https://api.{your-broker-domain}/api/crm/customers \
  -H "Authorization: Bearer eyJhbGciOi..."
```

## Refreshing

Access tokens expire after **15 minutes** (configurable per-broker). Exchange
the refresh token for a new access token:

```bash theme={null}
curl -X POST https://api.{your-broker-domain}/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "Ck9M5..." }'
```

Refresh tokens are single-use and rotate on every exchange. Store only the
latest pair.

## Revocation

Signing out of a session revokes its tokens immediately:

```bash theme={null}
curl -X DELETE https://api.{your-broker-domain}/auth/sessions/{session_id} \
  -H "Authorization: Bearer eyJhbGciOi..."
```

A revoked token returns `401` on the next request — no grace period.

## Two-factor authentication

Accounts with TOTP enabled must submit `totp_code` (or a backup code) alongside
the password. Login returns `202 TOTP_REQUIRED` otherwise.

## Customer session vs. staff session

Tokens carry a `type` claim (`"user"` or `"customer"`). Endpoints under
`/api/crm/*`, `/api/backoffice/*`, `/api/platform/*`, and `/api/admin/*`
accept user tokens only. Endpoints under `/api/customer/*` accept customer
tokens only. The mismatch returns `403`.

## Programmatic access (API tokens)

For long-lived machine-to-machine integrations — affiliate portals, BI
pipelines, KYC vendors — issue a scoped **API token** from the CRM's
Settings → API Access page. API tokens use the `Authorization: Bearer` header
like JWTs but never expire unless you set a TTL, and each token is limited to
an explicit set of scopes. See the CRM UI for details.