SDK — exchangeToken()
API Reference
Token Exchange
Exchange a long-lived service key for a short-lived signed token.
POST
SDK — exchangeToken()
POST /v1/auth/token
Exchange a long-lived service key for a short-lived GatelitSigned token. The gateway verifies the service key, signs a token with its internal secret, and returns it. No raw signing secret is ever exposed to your backend.
Use this to issue per-user tokens from your backend — authenticate with a service key, provide the user’s identity and optional constraints, and receive a token your frontend can use directly with any other gateway endpoint.
Auth
Only service keys are accepted at this endpoint. Signed tokens and OIDC are rejected.Request body
The issued token inherits the
orgId from the service key used to authenticate the exchange. This enables org-scoped provider key resolution for the downstream requests.
Response
token with the GatelitSigned scheme on all other gateway endpoints:
Examples
curl — minimal
curl — with model constraint and token cap
SDK — exchangeToken()
Errors
Authorizations
Long-lived service key for backend-to-backend use.
Format: GatelitKey glk_...
Create service keys in the dashboard under Settings → Service Keys.
Body
application/json
Subject identifier — typically the end user's ID.
Token lifetime in seconds (max 1 hour).
Required range:
1 <= x <= 3600Restrict to one model in provider/model format.
Cap output tokens per request.
End-user identifier for log filtering.
Available options:
api, eval