Mint a client token

POST https://gateway.roadie.paroaria.ai/v1/client-tokens
Authorization: Bearer rd_sk_prod_…
Content-Type: application/json

Exchange an end-user identity for a short-lived, end-user-scoped client token your app then uses to call the AI endpoints as that one end user. There are two paths, dispatched by the authenticating credential.

Authentication

Path A — a secret key (rd_sk_…): your backend names the end user explicitly.
Path B — a publishable key (rd_pk_…): a client app with no backend passes its existing identity provider’s ID token, which the gateway verifies against your project’s federated-auth config.

A client token cannot mint another token: presenting one fails 403 permission_error (client_token_cannot_mint).

Request body

Path A (secret key)

Field	Type	Required	Notes
`end_user`	object	yes	The end user to mint for.
`end_user.id`	string (1–256)	yes	Your stable identifier for the end user.
`end_user.plan`	string (1–256)	no	An asserted plan claim (a developer-set entitlement wins over it).
`end_user.attributes`	object	no	Free-form JSON, up to 4096 bytes serialized.
`ttl_seconds`	integer	no	Token lifetime. Defaults to `900` (15 min); clamped to `[1, 3600]`.
`scopes`	string[]	no	Subset of `ai.chat`, `ai.embed`, `ai.images`, `feedback`. Defaults to all four.

{
  "end_user": { "id": "user_42", "plan": "pro" },
  "ttl_seconds": 900,
  "scopes": ["ai.chat", "ai.embed"]
}

Path B (publishable key)

Field	Type	Required	Notes
`identity_token`	string (≤8192)	yes	Your IdP’s ID token (JWT). The gateway verifies issuer, audience, and signature against the project’s federated-auth config, then derives the end-user id (and optional plan claim) from it.
`ttl_seconds`	integer	no	As Path A.
`scopes`	string[]	no	As Path A.

{ "identity_token": "eyJhbGciOi…" }

Response

201 Created:

{
  "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6…",
  "expires_at": "2026-07-19T12:15:00.000Z",
  "end_user_id": "user_42"
}

token — the ES256 client token. Send it to the AI endpoints as Authorization: Bearer <token>. App code never needs to parse it.
expires_at — ISO-8601 expiry.
end_user_id — the resolved end-user id (from the body on Path A, or the verified IdP token on Path B).

Tokens are signed with rotating ES256 keys. The public verification keys are published at GET https://gateway.roadie.paroaria.ai/.well-known/jwks.json (unauthenticated). There is no per-token revocation route; keep TTLs short (the default is 15 minutes). A developer-set entitlement is resolved at mint time and always wins over any client- or IdP-asserted plan.

Rate limits

Minting is rate-limited per key (120/min) and per client IP (60/min). Exceeding either returns 429 rate_limit_error (mint_rate_limit_exceeded) with a Retry-After header.

Errors

Failures use the error envelope:

400 invalid_request_error — a malformed body (invalid_request); an empty or unknown scope (invalid_scope, param: "scopes"); end_user.attributes over 4096 bytes (attributes_too_large); Path B with no federated auth configured (federated_auth_not_configured) or an invalid project config (federated_config_invalid).
401 authentication_error — a bad or missing key; on Path B, an invalid identity token (invalid_identity_token).
403 permission_error — a client token attempting to mint (client_token_cannot_mint).
429 rate_limit_error — mint_rate_limit_exceeded.
503 internal_error — client-token signing is temporarily unavailable (signing_key_unavailable).

Introduction

Data plane

OpenAI-compatible

Control plane

Errors

Mint a client token

Authentication

Request body

Path A (secret key)

Path B (publishable key)

Response

Rate limits

Errors

​Authentication

​Request body

​Path A (secret key)

​Path B (publishable key)

​Response

​Rate limits

​Errors

Authentication

Request body

Path A (secret key)

Path B (publishable key)

Response

Rate limits

Errors