Authentication

All Revolab API requests require a valid API key passed as a Bearer token.

Header format

Include your API key in every request using the Authorization header:

curl -X POST https://api.revolab.ai/v1/tts \
  -H "Authorization: Bearer rvl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"nada-1.0-pro","text":"Hello","voice_id":"<your-voice-id>"}'

import os
import requests
 
headers = {
    "Authorization": f"Bearer {os.environ['REVOLAB_API_KEY']}",
    "Content-Type": "application/json",
}
 
response = requests.post(
    "https://api.revolab.ai/v1/tts",
    headers=headers,
    json={"model": "nada-1.0-pro", "text": "Hello", "voice_id": "<your-voice-id>"},
)

const headers = {
  Authorization: `Bearer ${process.env.REVOLAB_API_KEY}`,
  "Content-Type": "application/json",
};
 
const response = await fetch("https://api.revolab.ai/v1/tts", {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "nada-1.0-pro",
    text: "Hello",
    voice_id: "<your-voice-id>",
  }),
});

Replace rvl_live_... with your actual key. The prefix rvl_live_ identifies it as a Revolab secret key — never share this value.

Getting a key

Generate keys from the API Keys page in your dashboard. Each key has a name, creation date, and masked prefix shown in the dashboard (e.g., rvl_live_Ab1C...****). The full key is shown only once at creation time.

Key scopes

Every key has a scope chosen at creation: all (default), tts-only, or stt-only. A key whose scope does not cover an endpoint receives 403 forbidden — e.g. a tts-only key calling POST /v1/stt. Scopes also apply to the compatible APIs (speech endpoints need tts-only/all, transcription endpoints stt-only/all). Keys can optionally carry an expiry date; expired keys receive 401.

On the compatible surfaces, the vendor SDK’s own auth header also works — xi-api-key (ElevenLabs) and X-API-Key (Cartesia) — carrying the same rvl_live_ key. Everywhere else, authentication is strictly Authorization: Bearer.

Allowed IP addresses

A key can be pinned to the addresses your systems actually call from: single addresses or CIDR blocks, IPv4 and IPv6, up to 20 per list. Set it on the key in Dashboard → API keys; an Admin can also draw an organization-wide boundary in Settings → Organization → API keys. The two are intersected — a request must be admitted by every list that is set, so a key can pin itself further than the organization’s list, never wider.

Each list has a stage. Warn only serves every request and counts the ones a list would have refused, so you can read a week of real traffic before arming anything; Enforcing refuses them with 403 ip_not_allowed. Having no list allows every address — there is deliberately no way to save an empty list, because “empty” would read as “allow everything” to one person and “deny everything” to the next.

Console (browser) traffic is never checked, so an allowlist cannot lock an administrator out of the dashboard they would use to undo it.

Key safety

• Never hardcode keys in source code. Use environment variables or a secrets manager.
• Never commit keys to version control. Add .env to your .gitignore.
• Never expose keys client-side. Always call the Revolab API from a server or serverless function, not from browser JavaScript.
• Use one key per project. This makes it easy to rotate a single key if it is compromised without affecting other integrations.

Key rotation

If you suspect a key is compromised, rotate it immediately:

1. Go to the API Keys page in your dashboard.
2. Click Create key to generate a new key.
3. Update all services that use the old key with the new value.
4. Click Delete next to the old key to revoke it immediately.

All requests using a deleted key will immediately receive a 401 Unauthorized response.

Masked-prefix display

The dashboard shows your key in masked form (e.g., rvl_live_Ab1C...****). This lets you identify which key is which without exposing the full secret. The mask is applied at storage time — Revolab never stores your raw key, only a hashed form. This is why the full key is shown only once: it cannot be retrieved from our servers after creation.

Error responses

If your key is missing, invalid, or revoked, the API returns HTTP 401:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key format. Keys must start with 'rvl_live_'.",
    "request_id": "req_01HXYZ..."
  }
}

See the Error catalog for the full list of error codes.