Tokens

Create a one-time token

Mints a single-use, short-lived bearer token from the API key that authenticates this request. The token authenticates exactly one HTTP request or WebSocket connection to the APIs its parent key can reach, then expires. Authenticate with the API key itself — bearer callers are refused. See the [one-time tokens guide](/portal/ephemeral-tokens) for semantics and client patterns.

POST/auth/v1/tokens

Authorizations

Authorizationstringrequired

Your authentication credentials. Populate Basic $INWORLD_API_KEY — one-time tokens are minted with the parent API key itself, never with a bearer token.

Body

application/json

single_usebooleanrequired

Must be true. Only single-use tokens are supported; the token is consumed by its first successful authentication.

ttlstring

How long the token stays valid, as a duration in seconds (e.g. "300s"). Minimum 1 second, maximum 1 hour; defaults to 15 minutes. Mutually exclusive with expire_time.

expire_timestring

Absolute expiry timestamp, as an alternative to ttl. Capped at 1 hour from now. Mutually exclusive with ttl.

client_reference_idstring

Optional correlation ID of your own (for example a user or session ID). Printable ASCII, at most 256 characters. Echoed in the response and attached to the token for usage attribution.

Create a one-time token

curl https://api.inworld.ai/auth/v1/tokens \
  --request POST \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "single_use": true,
    "ttl": "300s",
    "client_reference_id": "user-4711-session-42"
  }'

200minted

{
  "name": "tokens/1f0d8e9a-1d2b-4c3d-8e9f-0a1b2c3d4e5f",
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "expireTime": "2026-09-01T12:05:00Z",
  "singleUse": true,
  "clientReferenceId": "user-4711-session-42",
  "createTime": "2026-09-01T12:00:00Z",
  "apiKey": "workspaces/my-workspace/apikeys/4aa6d7e9-3a62-4e19-a031-9558852115f2"
}