API keys

⚑Feature required: apiAccess

API access is gated by the apiAccess flag at the platform level and additionally must be enabled per team by a superadmin under Admin Settings → Teams → API Access Configuration. The API Keys tab is hidden otherwise.

Path: /settings → API Keys tab

API keys let external systems talk to TelAPI — primarily for initiating and querying WebRTC call sessions. The tab is only visible if a superadmin has enabled API access for your team (Admin Settings → Teams → API Access Configuration).

AccessADMIN+

Prerequisites

A superadmin must:

1. Enable API access for the team.
2. Configure allowed scopes the team can assign to keys.
3. Set max API keys (per team).
4. Optionally set max requests / day (rate limit).

Usage stats

The tab header shows:

Stat	Description
API Keys	Current count vs. maximum (e.g. 1 / 2).
Requests Today	Requests made today vs. daily limit, if configured.
Available Scopes	Scopes assignable to new keys.

Available scopes

Scope	Description
CREATE_CALL_TOKEN	Create call tokens for initiating WebRTC sessions.
READ_CALL_TOKEN	Read / query existing call tokens.
READ_TEAM_APPS	List the team's apps and their metadata — useful when your backend selects the endpoint dynamically.
READ_TEAM_USAGE	Read team usage aggregates, including TTS character usage.

These scopes apply to the browser/SDK portion of TelAPI when API access is enabled for the team. The async LLM webhook endpoint (/api/v1/webhooks) uses its own auth and isn't controlled by these scopes. See API authentication.

Columns

Column	Description
Name	Friendly name.
Scopes	Assigned scopes (chips).
Created	Creation timestamp.
Last Used	When the key was last used.

Key security

• The key value is shown only once at creation. Copy it immediately.
• After creation, the key is masked and cannot be retrieved.
• If lost, delete and re-create.

Credential retry jail

TelAPI tracks repeated authentication failures for API keys (and webhook credentials when enabled). After too many failures inside a short window, the credential is temporarily jailed and further requests are rejected until the jail expires.

Variable	Default	Purpose
API_CREDENTIAL_JAIL_ENABLED	true	Master switch for the jail.
API_CREDENTIAL_MAX_RETRIES	5	Failures allowed inside the window before jail.
API_CREDENTIAL_RETRY_WINDOW_MS	300000	Sliding window for counting failures (5 minutes).
API_CREDENTIAL_JAIL_MS	300000	How long a jailed credential stays blocked (5 minutes).
API_CREDENTIAL_JAIL_WEBHOOKS_ENABLED	true	Apply the same jail to webhook auth failures.

These settings live on the API host — see the environment variable index and API operations.

Workflows

Create a key

1. Click Create.
2. Enter a friendly Name.
3. Select Scopes.
4. Click Create. Copy the key shown.
5. Store securely in your application's config.

Delete a key

Use the row action; confirm. The key is invalidated immediately.

Screenshotguide/team-admin/api-keysneeds_review

Settings → API Keys tab

Highlight: usage stats bar, keys table with name/scopes/dates, create button

Reason: TelWeb v0.9.14 i18n and UI refactors changed labels/layout; screenshot needs visual review.

See also

• TelPhi SDK — primary consumer of API keys.
• Admin settings — where API access is enabled per team.