Authentication

platform v0.9.11verified 2026-05-14

⚑Feature required: webrtc

This feature is gated. Operators enable it per deployment in the Delphi Portal; if the flag is off, the surface described below is hidden from the UI and rejected by the API. See Feature flags for the full registry.

The browser & SDK API uses tenant-scoped API keys sent in the standard bearer header. Every request that isn't /health or an inbound webhook (/api/v1/webhooks/*) requires one. Keys are additionally restricted by a fixed set of scopes.

For the separate auth model used by the async LLM webhook endpoint, see Webhooks.

Where keys come from

A team admin creates an API key in Team settings → API keys in TelWeb. The key value is shown once, at creation, and never again. See the user-guide page for the workflow: API keys.

API key issuance is gated by the apiAccess feature flag at the platform level and by per-team enablement that a platform admin performs under Admin → Teams → API Access Configuration. If the API Keys tab is not visible to a team admin, one of those two is off — see Feature flags.

Request header

Send the key on every request in the standard bearer header:

Authorization: Bearer <api-key>

Use HTTPS only. TelAPI rejects plain-HTTP requests.

What a key is bound to

Binding	Where it's set
Tenant (team)	Implicit — every key belongs to exactly one team.
Scopes	Selected at creation. The team's available scopes are configured by a platform admin.
Daily request limit	Optional, set by a platform admin per team.
Lifetime	Until deleted. Keys do not expire on their own; rotate them on a schedule.

There is no "user" identity attached to a key . Two admins in the same team can both create keys with the same scopes; the audit trail records who created the key, but requests using the key are attributed to the team, not a person.

Rotation

To rotate a key:

1. Create a new key with the same scopes.
2. Deploy the new key everywhere it's used.
3. Confirm traffic on the new key in usage stats.
4. Delete the old key.

If a key leaks, delete it first and create a new one afterwards. Deletion takes effect immediately.

Errors

Status	Meaning
401	Key missing, malformed, or unknown (likely rotated or never existed).
403	Key valid, but doesn't have the scope required for this endpoint, or the platform's webrtc feature flag is off.
429	Key valid, but the team's daily request limit is exhausted.

See Errors for the full error envelope.

See also

• Scopes — what each scope allows.
• Call tokens — the main workflow your API key unlocks.
• API keys (user guide) — the TelWeb workflow for creating and deleting keys.
• Webhooks — the other TelAPI auth surface, separate from this one.
• Getting help — what to include when filing an auth issue.