Call tokens

A call token is a short-lived credential your backend mints via TelAPI and gives to a client app. The client exchanges the token for a WebRTC voice session against a Delphi endpoint, without ever holding the long-lived API key.

For pure text chat (no WebRTC), use POST /api/v1/sessions/token with mode: "text" instead — same CREATE_CALL_TOKEN scope, different mode. See Text chat.

Call tokens remain the primary pattern for voice-first integrations. Like the rest of the client-facing TelAPI surface, minting is gated by the webrtc feature flag — if the flag is off, mint requests return 403 regardless of scopes.

⚑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.

Why a token instead of the API key

• The API key authenticates your backend, not your end-user's browser. Putting it in client code would leak it.
• A call token is short-lived, bound to one endpoint, and single-use (or close to it — exact lifecycle in the generated reference). Loss of a token is bounded to one session.
• Tokens give you a clean cut-off point for tenant-side authentication: your backend decides who is allowed to start a call before minting a token.

High-level workflow

1. Choose the endpoint. Your tenant has one or more WebRTC-enabled endpoints attached to a flow. The endpoint ID is visible in TelWeb on the Flow Designer's Endpoint inspector.
2. Authenticate your end-user. Delphi does not authenticate your callers for you — that's your application's job.
3. Mint a token. Your backend calls TelAPI with CREATE_CALL_TOKEN scope. The response contains the token, the endpoint it's good for, and an expiry.
4. Hand it to the client. Pass the token (and the endpoint ID) to the browser/mobile client.
5. Start the call. The SDK uses the token to open a WebRTC session. On expiry / completion, the token is no longer valid.

The exact request/response shapes for the mint and read endpoints live in the generated reference — see API reference for status.

Operational considerations

• Expiry windows are short by design. Mint the token close to when the user actually starts the call. If your UX has a long "waiting room", refresh the token rather than minting one ahead of time.
• One token per call. Don't try to reuse a token across sessions. If the client retries after a network failure, mint a fresh token.
• Server-to-server only for minting. CREATE_CALL_TOKEN should live in a backend with a hardened secret store, not in a static SPA bundle.
• Audit at your side. Log who you minted a token for. TelAPI logs the mint itself but not your tenant-side user.

Errors

Common error responses when minting:

Status	Cause
400	Endpoint missing/unknown or the endpoint isn't WebRTC-capable.
401	API key missing or invalid — see Authentication.
403	API key lacks CREATE_CALL_TOKEN — see Scopes.
409	Endpoint in a state that doesn't allow new sessions (e.g. flow in archived state).
429	Team-level rate limit exhausted.

See Errors for the full envelope.

See also

• Text chat — mode: text session tokens and text ↔ voice migration.
• Authentication — how TelAPI accepts your backend's credentials.
• Scopes — CREATE_CALL_TOKEN and READ_CALL_TOKEN.
• Client SDK — the typed client your browser/mobile app should use.
• Endpoints (user guide) — endpoint concepts and where they live in TelWeb.