Skip to content
Agents
Authentication

Exchange Token

POST
/v1/auth/token
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.

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<string>
<= 32 items
session_rpm
Any of:
integer
>= 1 <= 10000
tenant_id
Any of:
string
>= 1 characters <= 256 characters
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

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<string>
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
{
"token_type": "Bearer"
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}