> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 (current TTS) and Pulse (current
> STT). Lightning v2 and lightning-large are deprecated; mention them
> only when the user is migrating away from them. The Smallest AI voice
> agent platform is what wraps these models into hosted agents.

# API Keys

> Create, manage, and rotate API keys to authenticate programmatic access to the voice agent platform and Smallest AI models.

Every request to the Smallest AI API is authenticated with a bearer API key. This page walks through creating a key from the console, using it in code, and rotating or revoking it when you need to.

```
Authorization: Bearer YOUR_API_KEY
```

The same key works across the voice agent platform (agents, calls, campaigns) and the underlying Smallest AI models (Pulse STT, Lightning TTS, Electron LLM, Hydra S2S). Usage is tracked per key against your account quota.

## Create an API key

#### Open the API Keys page

In the [Smallest AI console](https://app.smallest.ai/dashboard), open the **Developer** section in the left sidebar and select **API Keys**, or jump directly to [app.smallest.ai/dashboard/api-keys](https://app.smallest.ai/dashboard/api-keys?utm_source=documentation\&utm_medium=api-keys).

If this is your first key, you'll see an empty state with a **New API Key** button. Otherwise you'll see the list of existing keys with a **Create API Key** button in the top-right.

![API Keys empty state showing the New API Key button](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/9688555228b9ac9b272fab5022adf9af4df4c196d353a626929c4ec7c5a9e49c/products/atoms/pages/images/api-keys-empty-state.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060224Z&X-Amz-Expires=604800&X-Amz-Signature=4c799b06c2253b8e636cbeddfbf0f4f8b1a8fcd1da08caf51ff8ea1cf3536f95&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

#### Name the key

Click **New API Key** (or **Create API Key**). Enter a descriptive name identifying where the key will be used (e.g. `production`, `staging`, `dev-team`, or `my-voice-agent`). Names are for your reference only and can be reused across environments.

Click **Create API Key** in the dialog to confirm.

![Create New API Key dialog with the API Name field and Create API Key button](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/2cfb0af31885fc526653bd6a3110a6b42042da9942042218c324e772ec796922/products/atoms/pages/images/create-api-key-dialog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060224Z&X-Amz-Expires=604800&X-Amz-Signature=f3027ef549011a80c3fa18d6fee97c9f266eaa1000936e032983bfd315f5f60f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

#### Copy the key immediately

The generated key is shown once, then hidden. It starts with `sk_` followed by a random suffix. Click the copy icon and paste it somewhere safe before dismissing the dialog.

Keys are **shown only once at creation**. If you lose it, you'll need to create a new key and revoke the old one. There's no way to recover the value later.

![API Key Created dialog showing the generated key value and the Store this key securely warning](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/dd6d889589cd5c1872ba90562fd542eb6ca8364409bd2db6e1b3a97cc767b139/products/atoms/pages/images/api-key-created-copy.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060224Z&X-Amz-Expires=604800&X-Amz-Signature=63bead0e35ce3c5cbb56f205fb6f206cd7e2edec8f201d0f2a06e4d251571b50&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

#### Store it in your environment

Set the key as an environment variable so your code picks it up automatically:

```bash
export SMALLEST_API_KEY="sk_your_key_here"
```

Add the line to your `.bashrc` or `.zshrc` (or your team's secrets manager for production) to persist across sessions. Never hard-code the key in source, and never commit it to version control.

## Use the key

Include the key in the `Authorization` header on every request.

```bash cURL
curl -X GET "https://api.smallest.ai/atoms/v1/agent" \
  -H "Authorization: Bearer $SMALLEST_API_KEY"
```

```python Python
import os
from smallestai.atoms import AtomsClient

# Reads SMALLEST_API_KEY from environment automatically
client = AtomsClient()

# Or pass explicitly if you manage secrets differently
client = AtomsClient(api_key=os.environ["SMALLEST_API_KEY"])

agents = client.agent.list()
```

```javascript Node.js
import { AtomsClient } from "@smallest/atoms";

// Reads SMALLEST_API_KEY from environment automatically
const client = new AtomsClient();

const agents = await client.agent.list();
```

For the underlying models (TTS, STT, LLM, S2S), the same key authenticates every route:

```bash
curl -X POST "https://api.smallest.ai/waves/v1/tts" \
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: audio/wav" \
  -d '{"text": "Hello from Smallest AI.", "voice_id": "meher", "model": "lightning_v3.1_pro", "output_format": "wav"}' \
  --output hello.wav
```

## Manage existing keys

The API Keys page lists every key on your organization with its name, creation time, and controls to copy or revoke.

| Action     | How                                                                                                                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Search** | Filter the list by name with the search bar above the table.                                                                 |
| **Delete** | Click the trash icon next to a key to revoke it. Any request made with a revoked key returns `401 Unauthorized` immediately. |

Create one key per environment (production, staging, dev) so you can rotate or revoke each independently without breaking the others. Reusing a single key everywhere means a single leaked key forces a full-fleet rotation.

## Rotate a key

Rotating regularly limits blast radius if a key ever leaks. The recommended cadence: every 90 days, on any team change, or immediately if you suspect exposure (e.g. an accidental commit to a public repo).

1. Create a new key on the dashboard with a name reflecting the rotation (e.g. `production-2026-q3`).
2. Update your environment or secrets manager with the new value.
3. Deploy the change to every service that uses the key.
4. Confirm requests succeed with the new key.
5. Revoke the old key from the dashboard.

## Security

Your API key grants full account access. Never commit it to version control, expose it in browser or mobile client code, or share it in Slack / email / support tickets.

* Store keys in environment variables or a secrets manager, never in source.
* Add `.env` to `.gitignore` locally, and use platform secrets (GitHub Actions secrets, Vercel env vars, AWS Secrets Manager, etc.) for CI and production.
* Prefer a proxy server for browser and mobile apps: your app calls your backend, your backend calls Smallest AI with the key.
* Revoke immediately if a key is exposed and rotate the affected services.

## Errors

| Status                  | Meaning                                           | Action                                                                                                                   |
| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`      | Missing, malformed, or revoked API key            | Check the `Authorization` header. Confirm the key is active on the dashboard.                                            |
| `403 Forbidden`         | Key is valid but not authorized for this endpoint | Contact support if you expect access; some endpoints are gated per plan.                                                 |
| `429 Too Many Requests` | Rate limit or concurrency ceiling reached         | Wait and retry with backoff. See your plan on [Subscription & Plans](/voice-agents/platform/account/subscription-plans). |

For concurrency limits and rate-limit specifics, see [Concurrency & Limits](/models/api-reference/concurrency-and-limits) on the models side; the voice agent platform shares the same quota.