Manage team API keys
Use this guide to manage Settings → API Keys, or diagnose missing and disabled controls. Start by selecting the team whose integration credentials you need to manage.
| Your task | Start here |
|---|---|
| Connect a new backend | Create a scoped key, then verify a request |
| Replace or remove a credential | Rotate or revoke |
| Understand counters and controls | Key usage and list controls |
| Find missing API access | Availability checks |
Availability: from 0.9.18, the API Keys tab requires FEATURE_BROWSER_SDK=true for the deployment and at least one allowed API scope for the selected team. Team administrators and platform staff with administrative or global read access see the tab. Global read-only access lets you view keys, not change them. A platform superuser controls the team's allowed API scopes; a team administrator cannot grant them to their own team.
Check what is unavailable
Wait for Settings to finish loading before diagnosing missing access. A loading or failed team request does not mean that API access is disabled.
| What you see | What to check | What to do |
|---|---|---|
| API Keys is missing for your account | Your role and selected team | Ask a team administrator or platform administrator to confirm access for that team. |
| API Keys remains missing with the expected role | Whether the team has any allowed API scopes | Ask a platform superuser to check the team's API access configuration. An empty allowed-scope list keeps the tab hidden. |
| API key functionality is unavailable across the deployment | The deployment's Browser SDK capability | Ask the platform operator to check the effective feature configuration described below. |
| API Keys is visible but changes are unavailable | Whether you have global read-only access | Ask an administrator with write access to make the required change. |
| Creation is unavailable or fails despite write access | The displayed error, key quota, allowed scopes, API/SDK entitlement under any custom agreement, and applicable subscription restrictions | Follow Create a scoped key for key management and scope selection. Visibility alone does not guarantee permission or capacity to create a key. |
These are checks to distinguish causes, not a diagnosis from the missing tab alone. After access is corrected, reopen Settings for the intended team and verify that API Keys appears. If the task requires creating or changing a key, verify that operation separately using the verification steps below.
Deployment operator check
The API Keys tab, team SDK keys and the session routes exist only when the deployment enables Browser SDK. From 0.9.18 Browser SDK defaults to off, and the retired API access setting no longer enables it. Browser integration capabilities explains the flags, the WebRTC dependency and the upgrade steps. Ask your operator to check the effective value on both the Web UI and the API.
System session keys require an already authorized CREATE_CALL_TOKEN team scope.
Creating a key does not grant additional scopes. Operators provision the feature,
team entitlement and scopes explicitly.
Apply configuration changes with your deployment procedure, then verify the Web UI and the specific integration operation separately. For individual operations and authentication, use Make an HTTP API request, which explains how to read the API description that your deployment serves.
Credential retry jail
TelAPI can temporarily block a client IP after repeated credential failures, including subsequent requests with a valid key. This is separate from ordinary request-rate limits and the team's daily allowance. Successful authentication clears the failure counter before a jail begins; it does not bypass an already active jail.
The deployment operator controls these TelAPI startup settings:
| Variable | Range and default | Effect |
|---|---|---|
API_CREDENTIAL_JAIL_ENABLED | true or false; default true. | Enable credential retry protection. |
API_CREDENTIAL_MAX_RETRIES | Positive integer; default 5. | Failures that trigger a jail. |
API_CREDENTIAL_RETRY_WINDOW_MS | Milliseconds, minimum 1000; default 300000. | Failure-count window. |
API_CREDENTIAL_JAIL_MS | Milliseconds, minimum 1000; default 300000. | Jail duration. |
Use API_CREDENTIAL_JAIL_MS, not API_CREDENTIAL_JAIL_DURATION_MS. Confirm the variable is declared, resolved and passed into the affected TelAPI container, then apply the deployment's configuration activation procedure. Editing a cloud value alone does not change an already-running process. Use deployment configuration and activation and API rate-limit operations for the separate operational layers.
Do not trigger repeated invalid attempts against a shared customer IP merely to test this page. When a client receives 429, respect the returned retry guidance and correct its credential configuration. See HTTP error handling before deciding to retry.
Create a scoped key
- Select the intended team and open Settings → API Keys. Check Available Scopes and the API Keys quota before creating a credential.
- Choose Create API Key. Enter a meaningful Key Name (1–100 characters) and select only the scopes your integration needs. At least one scope is required. The creation dialog does not expose an expiry field.
- Choose Create once and wait for the result. Creation checks the team's allowed scopes, API/SDK entitlement and applicable subscription restrictions. The maximum key count comes from the plan (default one without a subscription when subscription management is enabled); disabling subscription management removes that plan-count check. Inactive ordinary keys still count; system-managed keys do not.
- In API Key Created, use the eye control if you need to reveal the value and the copy control to copy it. Store it in the integration backend's secret storage before choosing Done. The full value is returned only at creation; the list retains a prefix, not a recoverable secret. If copying fails, keep the dialog open and retry. If the value is lost, replace the key.
- Verify the required operation from the integration backend. A successful creation message proves storage, not that the requested route, scope or endpoint is available.
Keep this long-lived credential on the server. For a browser integration, your backend uses it to obtain the scoped session credentials described in Connect a browser application.
| Scope | Select it for |
|---|---|
CREATE_CALL_TOKEN | Browser session creation/control and runtime-capability discovery where the operation requires this scope. |
READ_TEAM_APPS | Listing the team's browser endpoints. Despite its name, the documented endpoint operation is not an unrestricted application-data API. |
READ_TEAM_USAGE | Reading team usage aggregates. |
READ_CALL_TOKEN | A selectable scope in this release; the session routes do not use it as their authorization requirement. Do not infer an available token-read operation from the label—check the specific HTTP operation. |
Only scopes allowed for the selected team appear in the form, and the backend validates them again. Changing a team's allowed-scope list does not rewrite existing keys: runtime authorization uses each key's stored scopes. Revoke or replace existing keys deliberately when reducing an integration's access.
Verify an authenticated request
After creating or rotating a key, follow Make an HTTP API request for the read-only GET /api/v1/endpoints check, pagination, error interpretation and retry decisions. It requires READ_TEAM_APPS and the deployment's TelAPI origin. Verify the actual operation your integration needs separately; a successful list request does not grant other scopes or establish session readiness.
If validation fails, check the key's active state, expiry, stored scopes, team state and entitlement before replacing it again. The request guide distinguishes those failures from per-IP limits and the credential-retry jail. Record safe status/code, time and request identifier without the credential.
Read key usage and list controls
The table shows Name, Key prefix, Scopes, Last Used, Requests and the delete action. It has no scope editor, rename/disable control or expiry editor in this screen. The backend update operation supports name and active state, but does not edit a key's scopes or expiration.
Last Used records successful key validation, which can precede a later scope rejection. Requests and Requests Today come from usage tracking with asynchronous, best-effort writes. They are not an exact audit ledger. Requests Today appears only when the team has a daily allowance. Its day starts at the Web UI server's local midnight. TelAPI's daily limiter uses UTC midnight and a per-process cached count. Multiple instances and delayed writes can therefore make the display and enforcement differ. Use the response and operator evidence when investigating a limit.
The screen requests up to 100 rows and does not present a next-page control. Platform readers can also see system-managed keys that ordinary team administrators do not see. Those keys support platform-managed browser access; do not delete them as routine cleanup. The quota counts ordinary keys, so it need not equal the visible row count.
Rotate or revoke a key
For planned rotation, create a replacement with the required scopes, store it in the backend, update the integration and verify the intended operation. Then use the old row's Delete API Key action and confirm Delete. Reopen the list and verify the old key fails a controlled request while the replacement still works. The deleted value cannot be restored. If the quota prevents overlapping keys, agree a maintenance window or an appropriate plan change before deleting a working credential.
For an exposed credential, revoke it promptly and replace the affected backend configuration. Deletion removes the key record used by subsequent validation; it does not cancel work already admitted or establish that previously issued session credentials have been revoked. Handle active browser sessions through their own lifecycle. A backend permission or subscription error can prevent deletion even when a row is visible; escalate to the platform administrator rather than assuming the key is gone.
Related
- Make an HTTP API request — to test a new or rotated key with a read-only request.
- Connect a browser application — to use a key for browser text, TTS or voice sessions.
- Feature availability — to check the Browser SDK and WebRTC capabilities with your operator.