Authenticate your app

If your app calls Dictation from your users’ devices (a desktop app, a mobile app or a web page), don’t ship your API key in it. Anyone can read a key out of an app or its network traffic and use it for anything your account can do. Instead, your server keeps the key and hands each signed-in user a temporary token when they’re about to dictate. The token works in place of your key, only for Dictation, and expires after a short window. If you send your own rewrite prompt, save it in your account so the app sends its name instead of the prompt.

Your server mints a token

When a signed-in user is about to dictate, your server sends your API key to the token endpoint and gets back a token that can only open Dictation.

Your app dictates with the token

The app sends the dictation request as usual, with the token in the Authorization header instead of your API key.

The token expires

The token stops opening new requests after the time you set, so a token that leaks is worth little.

Mint a Dictation-only token

Send POST to a token host with your API key and an access block that turns off every other product:

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

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

"product": "dictation" on its own doesn’t stop the token opening other products. Without the access block, a token minted for Dictation can also call Streaming, Sync, the Voice Agent API, TTS and LLM Gateway, billed to your account. Always send the access block from a token you hand to a user’s device.

Turning off sync and llm_gateway doesn’t affect Dictation, which calls them with its own credentials, not your token. llm_response, llm_instruction, rewrite_mode and saved prompts work the same with a Dictation-only token. Here’s the same request from a server, in Python and Node.js:

import os
import requests

DICTATION_ONLY = {
    "streaming": {"enabled": False},
    "sync": {"enabled": False},
    "speech_to_speech": {"enabled": False},
    "tts": {"enabled": False},
    "llm_gateway": {"enabled": False},
}

def mint_dictation_token() -> str:
    response = requests.post(
        "https://token.assemblyai.com/v1/token",
        headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
        json={"product": "dictation", "expires_in_seconds": 60, "access": DICTATION_ONLY},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()["token"]

const DICTATION_ONLY = {
  streaming: { enabled: false },
  sync: { enabled: false },
  speech_to_speech: { enabled: false },
  tts: { enabled: false },
  llm_gateway: { enabled: false },
};

export async function mintDictationToken() {
  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: "dictation", expires_in_seconds: 60, access: DICTATION_ONLY }),
  });
  if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
  return (await response.json()).token;
}

Serve this from an endpoint in your own backend that only your signed-in users can call. See Temporary tokens for every field the token endpoint takes.

Dictate with the token

On the device, send the dictation request exactly as you would with your API key, and put the token in the Authorization header. Both endpoints accept the token, and both allow requests from any web origin, so a browser can call Dictation directly:

async function dictate(audioBlob, { getToken }) {
  const token = await getToken(); // from your backend's mint endpoint

  const form = new FormData();
  form.append("config", JSON.stringify({}));      // config goes first
  form.append("audio", audioBlob, "audio.wav");

  const response = await fetch("https://dictation.assemblyai.com/v1/transcribe/live", {
    method: "POST",
    headers: { Authorization: token },
    body: form,
  });
  if (!response.ok) throw new Error(`Dictation failed: ${response.status}`);

  const result = await response.json();
  return result.llm_response || result.text; // fall back to the verbatim transcript
}

To upload while the user is still speaking, use the same token with the streaming request in Achieve lowest latency.

Keep tokens off the critical path

Fetching a token is one more round trip, so don’t wait to fetch it until the user starts speaking:

Fetch it early. Mint a token when the user is likely to dictate soon, such as when your dictation UI opens or the app comes to the front, and keep it until it’s close to expiring.
Mint a fresh token before it expires. expires_in_seconds is how long a token can wait before it opens a request, from 1 to 600. A request that opens in time runs to the end, even a long recording on /v1/transcribe.
Keep the window short. Until it expires, a token can open more than one request. A short window limits what a leaked token can do.
Pre-warm without a token. GET /warm needs no key or token, so you can warm the connection while the token is still on its way.

Mint the token before you start recording. If a streaming request is rejected with 401 partway through, the audio you already streamed can’t be sent again, so get a fresh token first and avoid starting a dictation on a token that’s about to expire.

Protect your mint endpoint

Usage through a token is billed to the API key that minted it, and a token carries nothing about which of your users it was minted for. Your backend is the only place that knows who asked for each token, so put your controls there:

Mint tokens only for users who are signed in to your app.
Rate-limit the endpoint per user, for example a few tokens a minute, which is plenty for dictation.
Log which user each token was minted for, so you can trace unusual usage back to an account and block it.

Keep your prompt off the device

If you rewrite with your own prompt, the prompt travels in every request your app sends, where anyone inspecting the traffic can read it. Save the prompt in your account instead, and have the app send only its name. Create the saved prompt once, from your server or as a deploy step, with your API key. Put {{ text }} where the transcript goes:

curl -X POST "https://llm-gateway.assemblyai.com/v1/prompts" \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app-cleanup",
    "prompt": "{\"model\": \"gemma-4-31b\", \"max_tokens\": 500, \"messages\": [{\"role\": \"system\", \"content\": \"Clean up this dictation for {{ user_name }}. Remove filler words and fix punctuation. Reply with only the text.\"}, {\"role\": \"user\", \"content\": \"{{ text }}\"}]}"
  }'

Then the app refers to it by name in the llm field of its dictation config, with any per-user values in prompt_replacements:

{
  "llm": {
    "aai_prompt": "my-app-cleanup",
    "prompt_replacements": { "user_name": "Sam" }
  }
}

The prompt itself never reaches the device, and you can change it without shipping a new version of your app. The model, max_tokens and other settings come from the saved prompt, so don’t send rewrite_mode or other llm fields with it. See Sending your own LLM request for the details.

Data zones

Mint the token on the token host for the data zone your app sends dictations to:

Dictation host	Token host
`https://dictation.assemblyai.com`	`https://token.assemblyai.com`
`https://dictation.us.assemblyai.com`	`https://token.us.assemblyai.com`
`https://dictation.eu.assemblyai.com`	`https://token.eu.assemblyai.com`

See Cloud endpoints & data residency.

Temporary tokens: every field the token endpoint takes.
Transcript rewriting: instructions, rewrite modes and saved prompts.
Error handling: status codes and retries.
Achieve lowest latency: upload while the user speaks.

Getting started

Features

API reference

Advanced

Guides

Authenticate your app

Mint a Dictation-only token

Dictate with the token

Keep tokens off the critical path

Protect your mint endpoint

Keep your prompt off the device

Data zones

​Mint a Dictation-only token

​Dictate with the token

​Keep tokens off the critical path

​Protect your mint endpoint

​Keep your prompt off the device

​Data zones

​Related pages

Mint a Dictation-only token

Dictate with the token

Keep tokens off the critical path

Protect your mint endpoint

Keep your prompt off the device

Data zones

Related pages