--- title: Exchange Token | Luma Agents --- POST /v1/auth/token Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/auth/token'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"scopes":["example"],"session_rpm":1,"tenant_id":"example","ttl":3600,"user_id":"example"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://agents.lumalabs.ai/v1/auth/token \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "scopes": [ "example" ], "session_rpm": 1, "tenant_id": "example", "ttl": 3600, "user_id": "example" }' ``` - Productionagents.lumalabs.ai/v1/auth/token Exchange an API key for a scoped, short-lived session JWT. The session JWT carries the API key's identity (client\_id, team\_id, key\_id) plus the partner-provided `user_id`, optional `tenant_id`, and granted `scopes`. Pass it as `Authorization: Bearer ` on every other SDK route. ## Authorizations - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Request Bodyrequired Media typeapplication/json *TokenRequest* Body for `POST /v1/auth/token`. Identity (client\_id, team\_id) comes from the API key in the `Authorization: Bearer` header — the body only carries the partner's end-user identifier, optional partner tenant, and scope/ttl overrides. object **scopes** Any of: - [Array\](#tab-panel-0-0) - [null](#tab-panel-0-1) Array\ <= 32 items null **session\_rpm** Any of: - [integer](#tab-panel-1-0) - [null](#tab-panel-1-1) integer \>= 1 <= 10000 null **tenant\_id** Any of: - [string](#tab-panel-2-0) - [null](#tab-panel-2-1) string \>= 1 characters <= 256 characters null **ttl** *Ttl* Token lifetime in seconds. Clamped to \[60, 86400]. integer default: 3600 >= 60 <= 86400 **user\_id** required *User Id* Your end-user's identifier. Used for billing attribution, conversation scoping, AND forwarded to upstream LLM providers (Anthropic `metadata.user_id`, OpenAI `user`) so abuse signals can be attributed back to the specific end-user. **Must be opaque** — pass a UUID, hash, or other non-identifying token. **Do not pass PII** (email, phone, full name); upstream providers explicitly disallow PII in this field per their terms of service. Maximum 256 characters (Anthropic's contract limit; enforced at this boundary so the abuse-attribution path can't silently fail). string <= 256 characters ## Responses ### 200 Successful Response Media typeapplication/json *TokenResponse* object **expires\_in** required *Expires In* Token lifetime in seconds from issuance. integer **scopes** required *Scopes* Scopes actually granted on this token. Array\ **session\_token** required *Session Token* Signed JWT. Pass as 'Authorization: Bearer ' on all SDK session, scope, and attachment routes. string **token\_type** *Token Type* Always 'Bearer'. string default: Bearer ##### Example ```json { "token_type": "Bearer" } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```