Exchange Token
const url = 'https://agents.lumalabs.ai/v1/auth/token';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', '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);}curl --request POST \ --url https://agents.lumalabs.ai/v1/auth/token \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "scopes": [ "example" ], "session_rpm": 1, "tenant_id": "example", "ttl": 3600, "user_id": "example" }'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 <session_token> on every other
SDK route.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”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
Token lifetime in seconds. Clamped to [60, 86400].
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).
Responses
Section titled “ Responses ”Successful Response
object
Token lifetime in seconds from issuance.
Scopes actually granted on this token.
Signed JWT. Pass as 'Authorization: Bearer
Always 'Bearer'.
Example
{ "token_type": "Bearer"}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}