Authentication

Every request to the Rabbitt Voice API carries an API key as a bearer token:

curl "https://api.rabbitt.ai/api/v1/agents" \
  -H "Authorization: Bearer rb_live_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A key belongs to exactly one organization. Every response it can produce is scoped to that organization's data — there is no way to reach another tenant's agents, calls, or reports with it.

Creating a key

Keys are created from API keys in your dashboard by an organization administrator. When you create one you choose:

• Scopes — what the key is allowed to do. See the table below.
• BYOK — whether this key's traffic runs on your own AI provider credentials instead of Rabbitt's. See Bring your own key below.
• Allowed origins — the web origins permitted to embed interviews using this key. Leave empty unless you are using the interview embed.
• Rate limit — requests per minute for this key. Defaults to 120.
• Expiry — optional. A key with an expiry stops working on its own, which is a good fit for a time-boxed integration.

Bring your own key

See Bring your own key for the full mechanism — per-capability credentials, the two independent toggles, enforcement, and billing. The rest of this section covers the key-creation flow specifically.

By default, calls and interviews made with a key run on Rabbitt's own AI provider accounts (OpenAI, Deepgram, and so on) and are billed from your credit balance. Turning BYOK on for a key means the opposite: its requests run entirely on your provider credentials — configured separately in billing settings — and are billed per minute rather than drawing down credits.

curl "https://api.rabbitt.ai/api/v1/api-keys" \
  -H "Authorization: Bearer $RABBITT_ADMIN_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "scopes": ["agents:read", "executions:read"],
    "byok": true
  }'

A few things follow directly from that:

• It is decided once, at creation, and cannot be changed afterward. BYOK sets how the key is billed, so flipping it on a live key would silently reprice traffic already in flight. Create a new key instead of trying to convert an existing one.
• It is independent of your organization's dashboard BYOK setting. That setting governs interviews run from the Rabbitt dashboard; a key's byok flag governs only that key's own API traffic. Neither one reads the other, so one organization can run its dashboard on Rabbitt's credentials while an integration runs on its own, or hold both a BYOK and a non-BYOK key at the same time with different billing.
• It requires your provider credentials to already be configured — all three. A BYOK key's requests never fall back to Rabbitt's credentials, so creating one is refused with 400 BYOK_NOT_READY unless you already have a verified key for the voice LLM, speech-to-text, and text-to-speech engines your agents use. Add those in billing settings first; the same provider key can usually cover more than one of the three.

Scopes

A key can only be granted scopes the person creating it already holds, so a key can never be used to escalate past its creator's own permissions.

Calling an endpoint without its required scope returns 403 with code PERMISSION_DENIED.

Live and test keys

Keys are prefixed rb_live_ or rb_test_. The prefix is part of the key and is checked on every request, so a test key can never be mistaken for a live one by an environment variable pointing at the wrong place.

Keeping keys safe

For browser-side interviews, your server calls POST /v1/interviews/{id}/embed-token and passes the resulting token to the page. That token:

• expires in minutes rather than never,
• works only for one interview,
• works only from the origins registered on the key.

That is the full flow in the embed guide.

Rotating a key

Because keys are independent of each other, rotation has no downtime:

1. Create a new key with the same scopes.
2. Deploy it to your servers.
3. Confirm traffic has moved — the dashboard shows each key's last-used time.
4. Revoke the old key.

Errors

See Errors for the full envelope.