▸ API Authentication

The API uses a two-tier authentication model:

1. Tenant authentication

Server-to-server calls are authenticated with your tenant API key and secret, sent as headers. The secret is shown only once, when the tenant is created in the admin back-office — store it securely.

2. Mint a user token

Your backend exchanges its tenant credentials for a short-lived JWT scoped to one of your users (identified by the external_id you assigned). The end-user's client then uses this token — it never sees your tenant secret.

POST /api/v1/users/{external_id}/token

# Request
curl -X POST https://yama.example.com/api/v1/users/ext-alice/token \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Secret: sk_xxx"

# 201 Created
{
  "token": "eyJhbGciOiJIUzI1Ni␣...",
  "user": { "id": "6b3e9a1c-8d2f-4f7a-9c1e-2a4b6d8e0f12", "external_id": "ext-alice", "display_name": "Alice" }
}

The JWT (HS256) carries the user and tenant ids and expires after 24 hours. Mint a fresh one when it expires.

3. User authentication

The end-user's client sends the JWT as a bearer token on every call.

GET /api/v1/me — returns the current user (useful to verify a token).

# Request
curl https://yama.example.com/api/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni␣..."

# 200 OK
{
  "id": "6b3e9a1c-8d2f-4f7a-9c1e-2a4b6d8e0f12",
  "external_id": "ext-alice",
  "display_name": "Alice",
  "tenant_id": 7,
  "status": "connected"
}

Errors