API Keys

API keys let you use TTSBuddy programmatically — from the CLI tool, custom scripts, or AI agents. Each key is tied to your account and subscription.

Creating a Key

1. Sign in to ttsbuddy.com
2. Go to Dashboard → Settings (/dashboard)
3. Scroll to the API Keys section
4. Click Create Key
5. Give your key a name (e.g., "My CLI Tool" or "CI Pipeline")
6. Copy the key immediately — it's shown only once

warning

The full API key is displayed once at creation. If you lose it, revoke the key and create a new one.

Key Format

Keys follow the format:

ttsb_<public_id>_<secret>

• ttsb_ — prefix (always the same)
• <public_id> — 8 hex characters, visible in dashboards and logs
• <secret> — 48 hex characters, never stored or displayed after creation

Example: ttsb_a1b2c3d4_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8

The server stores only a SHA-256 hash of the secret. The full key cannot be recovered.

Using Your Key

Environment Variable (recommended)

export TTSBUDDY_API_KEY="ttsb_a1b2c3d4_..."

Add to your shell profile (~/.zshrc, ~/.bashrc) for persistence.

Config File

ttsbuddy config set key ttsb_a1b2c3d4_...

Stored at ~/.ttsbuddy/config.json with 0600 file permissions.

CLI Flag

ttsbuddy speak "Hello" -k "ttsb_a1b2c3d4_..."

tip

Prefer the environment variable or config file over the -k flag. Flags are visible in shell history, ps output, and process listings.

HTTP Header

For direct API calls:

curl -X POST https://ttsbuddy.com/v1/agent-tts \
  -H "Authorization: Bearer ttsb_a1b2c3d4_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world"}'

Managing Keys

Viewing Keys

The API Keys section on the Settings page shows all your keys:

• Display key (ttsb_<public_id>) — the public identifier
• Name
• Created date
• Last used date
• Call count

The secret portion is never shown after creation.

Renaming

Hover over a key's name to reveal the pencil icon, then click to edit the name inline. Press Enter to save or Escape to cancel. Useful for identifying which key is used where.

Revoking

Click the revoke button and confirm. Revoked keys are immediately invalid — any application using that key will start getting 401 INVALID_KEY errors.

note

Revoking cannot be undone. Create a new key if you need to restore access.

Limits

• Maximum 1 active key per account
• Need more? Revoke unused keys first

Security

• Never share your API key or commit it to version control
• Add to .gitignore: any file containing your key (.env, config files)
• Rotate periodically: revoke old keys and create new ones
• Key redaction: The CLI automatically redacts keys in output, showing only ttsb_<public_id>_...
• File permissions: ~/.ttsbuddy/config.json is created with 0600 (owner read/write only) in a 0700 directory

If you suspect a key has been compromised, revoke it immediately in the dashboard and create a new one.

Plan Access

All standard TTSBuddy plans include API access:

Plan	API Access	Monthly TTS Minutes	File Retention
Free	Yes	Limited	1 day
Pro	Yes	Higher limit	7 days
Ultimate	Yes	Highest limit	30 days

Custom or promotional plans may have different entitlements. If you see a "No API access" error, check your plan details on the Billing page or contact support.

Next Steps

• Install the CLI — get started with ttsbuddy speak
• API Reference — full endpoint documentation
• View plans — compare available plans