Temporary tokens

A temporary token lets a browser or an app use an AssemblyAI product without your API key. Your server mints the token with your key, hands the token to the client, and the client uses it in place of the key. Each token expires after a short window, usage through it is attributed to the key that minted it, and a token cannot mint another token. Keep your API key on your server. Anything a client receives, including a token, can be read by that client, so keep each token’s window short and mint a new one for each connection.

Mint a token

Send POST to a token. host with your API key in the Authorization header and a JSON body. Only the token. hosts accept this request:

Host	Serves
`https://token.assemblyai.com/v1/token`	Nearest region, either zone
`https://token.us.assemblyai.com/v1/token`	US data zone
`https://token.eu.assemblyai.com/v1/token`	EU data zone

Mint on the host of the zone your sessions connect to.

curl -X POST "https://token.assemblyai.com/v1/token" \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "streaming", "expires_in_seconds": 60}'

The response is JSON with the token in its token field:

{ "token": "<temporary token>", "expires_in_seconds": 60 }

Use the token

Pass the token in place of your API key. A server can send it in the Authorization header, as it would your key. A browser cannot set headers on a WebSocket handshake, so it passes the token in the token query parameter of the WebSocket URL instead. Each product page shows the exact WebSocket URL and parameters. Mint a fresh token for each connection. Until its window closes, a token can open more than one session, so keep expires_in_seconds short.

Request fields

Field	Required	Description
`product`	Yes	The product the token is minted for. See the list below.
`expires_in_seconds`	Yes	How long the token can wait before it opens a session, from 1 to 600.
`max_session_duration_seconds`	No	Caps the session opened with the token. At least 60.
`access`	No	Settings per product that narrow what the token can open. See Limit what a token can do.

Products

Product	Aliases
`streaming`	`realtime`
`speech_to_speech`	`voice_agent`, `agent`
`sync`
`dictation`
`tts`
`llm_gateway`

Each product page shows how its client uses the token:

Limit what a token can do

A token can open any product your account can, unless you narrow it. The access field on the request narrows it for that one token. Your API key and account are not changed, and a token minted without access behaves as it does without it. Each product in access is keyed by product name or alias and takes:

Field	Default	Description
`enabled`	`true`	Set to `false` to stop the token from opening that product.
`models`	Not set	Limits per model. Only `llm_gateway` takes it.

Each model in models takes these optional limits. Each one is a whole number of 1 or more.

Limit	Meaning
`rpm`	Requests per minute made with this token.
`tpm`	Tokens per minute made with this token.
`max_tokens`	The largest `max_tokens` a request may set.
`max_prompt_size`	The longest prompt, in characters.

Products you leave out of access are not restricted by the token. List each product once: streaming and realtime name the same product, so listing both is an error.

Defaults for LLM Gateway limits

Case	Result
A model you do not list under `models`	10 requests per minute. Prompt size and `max_tokens` are not checked.
A listed model with `rpm` unset	10 requests per minute.
A listed model with `tpm` unset	Derived from `rpm`.
A listed model with `max_tokens` unset	The gateway’s default `max_tokens`.
A listed model with `max_prompt_size` unset	5000 characters.

Tutorials

1. Open one product only

A token for a real-time transcription page should not open text-to-speech, a voice agent session, or the LLM Gateway. Mint it with those products disabled:

curl -X POST "https://token.assemblyai.com/v1/token" \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "streaming",
    "expires_in_seconds": 60,
    "access": {
      "tts": { "enabled": false },
      "speech_to_speech": { "enabled": false },
      "llm_gateway": { "enabled": false }
    }
  }'

2. Limit one LLM Gateway model

To let a chat widget use one model at a set rate, mint an llm_gateway token with limits for that model. Other models are not listed, so they get the default of 10 requests per minute:

import os

import requests

response = requests.post(
    "https://token.assemblyai.com/v1/token",
    headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
    json={
        "product": "llm_gateway",
        "expires_in_seconds": 120,
        "access": {
            "llm_gateway": {
                "enabled": True,
                "models": {
                    "claude-sonnet-4-6": {
                        "rpm": 20,
                        "tpm": 40000,
                        "max_tokens": 500,
                        "max_prompt_size": 8000,
                    }
                },
            }
        },
    },
)
response.raise_for_status()
token = response.json()["token"]

const response = await fetch("https://token.assemblyai.com/v1/token", {
  method: "POST",
  headers: {
    Authorization: process.env.ASSEMBLYAI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    product: "llm_gateway",
    expires_in_seconds: 120,
    access: {
      llm_gateway: {
        enabled: true,
        models: {
          "claude-sonnet-4-6": {
            rpm: 20,
            tpm: 40000,
            max_tokens: 500,
            max_prompt_size: 8000,
          },
        },
      },
    },
  }),
});
if (!response.ok) throw new Error(`token request failed: ${response.status}`);
const { token } = await response.json();

A request that sets max_tokens above 500, or a prompt longer than 8000 characters, is refused by the gateway. The same token can still call other models, at the default of 10 requests per minute.

3. Handle a rejected request

The API checks the whole request before it mints anything and returns every problem at once. A problem with the request body returns 400 with the problems in detail:

{
  "detail": [
    "product 'tts' does not take model limits, only 'llm_gateway' does"
  ]
}

Unknown fields inside access, such as a misspelled enabled or a limit that is not one of the four above, return 422 with the field named in the error. A 401 or 403 means the API key was not accepted. A 500 or 502 means the token could not be issued right now; retry with backoff.

Getting started

Build & Evaluate

Administration

Trust & security

Mint a token

Use the token

Request fields

Products

Limit what a token can do

Defaults for LLM Gateway limits

Tutorials

1. Open one product only

2. Limit one LLM Gateway model

3. Handle a rejected request

​Mint a token

​Use the token

​Request fields

​Products

​Limit what a token can do

​Defaults for LLM Gateway limits

​Tutorials

​1. Open one product only

​2. Limit one LLM Gateway model

​3. Handle a rejected request

Mint a token

Use the token

Request fields

Products

Limit what a token can do

Defaults for LLM Gateway limits

Tutorials

1. Open one product only

2. Limit one LLM Gateway model

3. Handle a rejected request