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. 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 per client IP across API keys and session WebSockets. By default, the fifth failure within five minutes temporarily jails the IP for five minutes, including requests with valid credentials. Successful authentication clears the retry counter before a jail starts.

Variable	Default	Purpose
API_CREDENTIAL_JAIL_ENABLED	true	Master switch for the jail.
API_CREDENTIAL_MAX_RETRIES	5	Failure count that triggers the jail.
API_CREDENTIAL_RETRY_WINDOW_MS	300000	Window from the first failure (5 minutes).
API_CREDENTIAL_JAIL_MS	300000	How long a jailed IP stays blocked (5 minutes).

These settings require installation-level configuration and container recreation. See API server config → API credential retry jail for SSM paths, required manifest and Compose mappings, the v0.9.17.0 deployment fix, and verification steps. The duration variable is API_CREDENTIAL_JAIL_MS; API_CREDENTIAL_JAIL_DURATION_MS is not supported.

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.