Skip to content
RelationsAI
Getting started

Authentication

Every request to the RelationsAI API carries an API key in the Authorization header. This page explains the header format, how the key decides which workspace and mode you act in, and what the API returns when authentication fails. For the exact rules, see Authentication in API fundamentals.

Before you begin

You need an API key, created in the RelationsAI platform under Settings → API Keys (see Get an API key) and a workspace that is enabled for the API preview.

Sending your key

Send the key as a Bearer token on every request, over HTTPS:

Text
Authorization: Bearer rai_test_...
curl https://voice-api.relationsai.com/v1/workspace \ -H "Authorization: Bearer <token>"

GET/workspace is the best first request: it answers 200 OK with the workspace, the key's name, environment, effective scopes and expiry, the workspace's capabilities and the limits that apply. It needs no scope beyond workspace:read, which every key has, and it never changes anything.

JSONJSON
{
  "id": "ws_7Hk2Lm9QxR4tB8vN3cZp6W",
  "object": "workspace",
  "livemode": false,
  "name": "Acme Lending",
  "api_key": {
    "id": "key_4Nf8Gt2Hx6Jq9Lm3Pv7Rs1",
    "name": "CRM sync (test)",
    "environment": "test",
    "scopes": ["workspace:read", "agents:read", "numbers:read", "calls:read", "calls:write", "transcripts:read", "recordings:read", "analysis:read"],
    "created_at": "2026-10-20T08:15:00.000Z",
    "expires_at": null
  }
}

Only RelationsAI API keys are accepted. Console sign-in sessions, other tokens and older sk_live_ keys are refused.

Workspace and mode

A key belongs to exactly one workspace and one mode, and there is no header or parameter to pick either:

  • rai_test_... keys act in test mode ("livemode": false): simulated calls, no charges.
  • rai_live_... keys act in live mode ("livemode": true): real calls, charged to the workspace.

Objects created with a test key exist only in test mode, and a live key can never read them (and the other way round). An id from the other mode, or from another workspace, answers resource_not_found, exactly as if it did not exist. See Environments.

Scopes

Each key carries scopes such as calls:read or campaigns:write, chosen when it is created. Each operation needs one scope, shown in the API reference. A request outside the key's scopes fails with insufficient_scope, and details.required_scopes says which scope was missing. See API keys for the full list.

A key can never do more than the member who created it is allowed to do right now. If that member's role changes, the key's effective scopes shrink with it; if the member leaves the workspace, the key stops working. Both cases answer insufficient_permissions.

Keep keys on your server

API keys are secrets. Use them only from server-side code: never in a web page, a mobile app, a browser extension or anything else you ship to users.

The API enforces this for live keys: a request that carries an Origin header (which browsers add) with a live key is refused with live_key_not_allowed_in_browser, before the key is even checked. Test keys can be used from browser-based tools. If your workspace has an IP allowlist in its security settings, API requests from other addresses are refused with ip_not_allowed.

Authentication errors

  • authentication_required (401): No Authorization header, a scheme other than Bearer, or an empty token. Send Authorization: Bearer <key>.
  • invalid_api_key (401): A typo, a truncated key, extra quotes or whitespace, or a credential that is not an API key. Copy the key again from where you stored it; if it is lost, create a new one.
  • api_key_expired (401): The key reached its expiry, or its rotation grace period ended. Switch to the replacement key, or create a new key.
  • api_key_revoked (401): An admin revoked the key. Ask an admin for a new key.
  • legacy_api_key_not_supported (401): An older sk_live_ key. Create a scoped key under Settings → API Keys.
  • insufficient_scope (403): The key lacks the scope the operation needs. Create a key with the scopes in details.required_scopes.
  • insufficient_permissions (403): The key's creator no longer has that permission, or left the workspace. Ask an admin to create a new key from an account that holds the permission.
  • api_access_not_enabled (403): The workspace is not enabled for the API preview. Write to support@relationsai.com.
  • ip_not_allowed (403): The workspace IP allowlist does not include your server. Ask an admin to add your server's address in the console security settings.
  • live_key_not_allowed_in_browser (403): A live key sent from browser code. Call the API from your server; use a test key in browser tools.

None of these errors did anything: retrying the same request will fail the same way until you fix the cause. If the API cannot check a key because of a temporary problem on our side, it refuses the request with service_unavailable rather than letting it through; retry after Retry-After seconds.

Check that it works

Run the request above. A 200 OK with the expected name, livemode and api_key.scopes means the key, the workspace and the mode are right. Then continue with the Quickstart.

QuickstartAPI keys