Ephemeral keys

Short-lived tokens for one end user’s device, with their own credit ceiling.

When and why to call these: the ephemeral keys guide.

What a token may be minted with

GET /v1/ephemeral-keys/limits

curl

curl "https://api.lumavox.ai/v1/ephemeral-keys/limits" \
  -H "Authorization: Bearer $API_KEY"

Responses

Status	Description
200	application/json — The ceilings this platform will mint within
401	Missing or invalid credentials
403	The key is valid but its scopes do not cover this capability — a key limited to tts gets this from /v1/images rather than a 401
422	The request failed validation
429	Rate limit exceeded

200 response body

Field	Type	Description
max_ttl_seconds	integer	The platform’s longest lifetime for a key.
default_ttl_seconds	integer
max_credit_limit_micros	integer	The platform’s largest credit limit for a key.
plan_max_ttl_seconds	integer or null	Your plan’s longest lifetime for one end user’s key; null sets none. A key is held to the tighter of this and max_ttl_seconds.
plan_max_credit_limit_micros	integer or null	Your plan’s largest credit limit for one end user’s key, in micro-credits; null sets none. A key is held to the tighter of this and max_credit_limit_micros.
plan_max_live_keys	integer or null	How many live keys one end user may hold on your plan; null sets none.
grantable_scopes	array of string

This organisation’s tokens

GET /v1/ephemeral-keys

curl

curl "https://api.lumavox.ai/v1/ephemeral-keys" \
  -H "Authorization: Bearer $API_KEY"

Query parameters

Name	Type	Required	Description
live_only	boolean		Default true.
limit	integer		How many to answer, 1 to 200. 1–200. Default 50.
cursor	string		The next_cursor of the page before. At least 1 characters.

Responses

Status	Description
200	application/json — Live tokens, unless you asked for the rest too
400	The request could not be read: malformed JSON
401	Missing or invalid credentials
403	The key is valid but its scopes do not cover this capability — a key limited to tts gets this from /v1/images rather than a 401
422	The request failed validation
429	Rate limit exceeded

200 response body

Field	Type	Description
data	array of EphemeralKeyInfo
data[].id	string
data[].label	string or null
data[].prefix	string
data[].last4	string
data[].scopes	array of string
data[].credit_limit_micros	integer	The most this key may spend, in micro-credits.
data[].credits_spent_micros	integer	What it has spent, as its end user DO last settled — at the end, or daily for a long-lived key. Final once settled_at is set.
data[].credits_remaining_micros	integer	Micro-credits: 1 credit is 1,000,000.
data[].agent_ids	array of string or null
data[].created_by_api_key_id	string or null
data[].created_by_clerk_user_id	string or null
data[].end_user_id	string or null
data[].created_at	string (date-time)
data[].expires_at	string (date-time)
data[].last_used_at	string (date-time) or null
data[].revoked_at	string (date-time) or null
data[].revoked_reason	string or null
data[].settled_at	string (date-time) or null	When its end user DO settled it for the last time — what it spent and what came back are final from then. null while it is live, and for a few seconds after it ends, longer while a memory job it paid for still runs.
data[].active	boolean
next_cursor	string or null	Pass as cursor for the next page; null when this is the last.

Mint a token for one end user

POST /v1/ephemeral-keys

A token is prepaid: its credit_limit_micros is set aside from your balance when it is minted — refused with 402 when the balance cannot cover it — and what it does not spend comes back when it expires, runs out or is revoked. Your plan caps a token’s limit and lifetime for one end user, how many each end user may hold, how many you mint a minute (429) and how much credit live tokens may hold at once.

curl

curl -X POST "https://api.lumavox.ai/v1/ephemeral-keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credit_limit_micros":0,"end_user_id":"..."}'

Request body (application/json)

Field	Type	Required	Description
scopes	array of string		Default ["agent"].
credit_limit_micros	integer	Required	The most this key may spend, in micro-credits (1 credit is 1,000,000). Required — there is no unlimited key.
expires_in_seconds	integer		Default 900.
end_user_id	string	Required
agent_ids	array of string or null
label	string or null		At most 120 characters.

Responses

Status	Description
201	application/json — The token, returned once — only a hash is stored
400	The request could not be read: malformed JSON
401	Missing or invalid credentials
402	The balance cannot set aside this credit limit, or the organisation is suspended or on no plan
403	Minted with an ephemeral key, or a revoked one
422	Scopes other than [“agent”], a minting key without agent, an unknown end user, or a limit out of range
429	The plan’s ephemeral keys a minute, or a request window — Retry-After says when

201 response body

Field	Type	Description
id	string
label	string or null
prefix	string
last4	string
scopes	array of string
credit_limit_micros	integer	The most this key may spend, in micro-credits.
credits_spent_micros	integer	What it has spent, as its end user DO last settled — at the end, or daily for a long-lived key. Final once settled_at is set.
credits_remaining_micros	integer	Micro-credits: 1 credit is 1,000,000.
agent_ids	array of string or null
created_by_api_key_id	string or null
created_by_clerk_user_id	string or null
end_user_id	string or null
created_at	string (date-time)
expires_at	string (date-time)
last_used_at	string (date-time) or null
revoked_at	string (date-time) or null
revoked_reason	string or null
settled_at	string (date-time) or null	When its end user DO settled it for the last time — what it spent and what came back are final from then. null while it is live, and for a few seconds after it ends, longer while a memory job it paid for still runs.
active	boolean
key	string	The token, in full. Shown once: it is signed rather than stored, so it cannot be shown again.

One token

GET /v1/ephemeral-keys/{key_id}

A token as the organisation’s records hold it, live or not. After a revoke, read it until settled_at is set: its spend and refund are final from then.

curl

curl "https://api.lumavox.ai/v1/ephemeral-keys/$KEY_ID" \
  -H "Authorization: Bearer $API_KEY"

Path parameters

Name	Type	Required	Description
key_id	string	Required

Responses

Status	Description
200	application/json — The token
400	The request could not be read: malformed JSON
401	Missing or invalid credentials
403	The key is valid but its scopes do not cover this capability — a key limited to tts gets this from /v1/images rather than a 401
404	Unknown ephemeral key id
422	The request failed validation
429	Rate limit exceeded

200 response body

Field	Type	Description
id	string
label	string or null
prefix	string
last4	string
scopes	array of string
credit_limit_micros	integer	The most this key may spend, in micro-credits.
credits_spent_micros	integer	What it has spent, as its end user DO last settled — at the end, or daily for a long-lived key. Final once settled_at is set.
credits_remaining_micros	integer	Micro-credits: 1 credit is 1,000,000.
agent_ids	array of string or null
created_by_api_key_id	string or null
created_by_clerk_user_id	string or null
end_user_id	string or null
created_at	string (date-time)
expires_at	string (date-time)
last_used_at	string (date-time) or null
revoked_at	string (date-time) or null
revoked_reason	string or null
settled_at	string (date-time) or null	When its end user DO settled it for the last time — what it spent and what came back are final from then. null while it is live, and for a few seconds after it ends, longer while a memory job it paid for still runs.
active	boolean

Revoke a token

DELETE /v1/ephemeral-keys/{key_id}

Answers at once, with the figures from before its end user’s records settle it. GET /v1/ephemeral-keys/{key_id} reads the final ones once settled_at is set — seconds, longer while a memory job it paid for still runs.

curl

curl -X DELETE "https://api.lumavox.ai/v1/ephemeral-keys/$KEY_ID" \
  -H "Authorization: Bearer $API_KEY"

Path parameters

Name	Type	Required	Description
key_id	string	Required

Responses

Status	Description
200	application/json — The token is dead; anything in flight still settles
400	The request could not be read: malformed JSON
401	Missing or invalid credentials
403	The key is valid but its scopes do not cover this capability — a key limited to tts gets this from /v1/images rather than a 401
404	Unknown ephemeral key id
422	The request failed validation
429	Rate limit exceeded

200 response body

Field	Type	Description
id	string
label	string or null
prefix	string
last4	string
scopes	array of string
credit_limit_micros	integer	The most this key may spend, in micro-credits.
credits_spent_micros	integer	What it has spent, as its end user DO last settled — at the end, or daily for a long-lived key. Final once settled_at is set.
credits_remaining_micros	integer	Micro-credits: 1 credit is 1,000,000.
agent_ids	array of string or null
created_by_api_key_id	string or null
created_by_clerk_user_id	string or null
end_user_id	string or null
created_at	string (date-time)
expires_at	string (date-time)
last_used_at	string (date-time) or null
revoked_at	string (date-time) or null
revoked_reason	string or null
settled_at	string (date-time) or null	When its end user DO settled it for the last time — what it spent and what came back are final from then. null while it is live, and for a few seconds after it ends, longer while a memory job it paid for still runs.
active	boolean

The credential you are calling with

GET /v1/token

Read it when a session starts and after a response — not on a timer.

curl

curl "https://api.lumavox.ai/v1/token" \
  -H "Authorization: Bearer $API_KEY"

Responses

Status	Description
200	application/json — What this credential is, what it may do and what it has left
401	Missing or invalid credentials
422	The request failed validation
429	Rate limit exceeded