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

The API Keys tab requires API access to be enabled for the deployment and at least one allowed API scope for the selected team. The tab is visible to team administrators and platform staff with the relevant administrative or global read access. Global read-only access allows inspection, not changes.

Your platform operator controls deployment availability. A platform superuser controls the team's allowed API scopes; a team administrator cannot grant those scopes 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 establish that API access has been disabled.

What you see	What to check	Next step
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 API access feature	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

FEATURE_API_ACCESS=false disables the API access UI feature. When the setting is absent, the checked implementation enables that feature; role and team restrictions still apply. Use the explicit values true and false when configuring it.

Check the effective configuration of both the web application and TelAPI. TelAPI also uses FEATURE_API_ACCESS to decide whether to register its conditional API routes when the server starts. FEATURE_WEBRTC is a separate switch and does not replace this check. A hidden UI tab is not evidence that an existing key was revoked or that every HTTP endpoint is disabled.

Use your deployment's configuration rollout procedure for changes, then verify the web UI and the specific integration operation independently. For API operations and authentication, use the selected HTTP reference. That snapshot retains its own patch1 identity; verify your deployment rather than treating it as a complete reference for this platform release.

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:

Setting	Default	Meaning
API_CREDENTIAL_JAIL_ENABLED	true	Enable credential retry protection.
API_CREDENTIAL_MAX_RETRIES	5	Failures that trigger a jail; positive integer.
API_CREDENTIAL_RETRY_WINDOW_MS	300000	Failure-count window in milliseconds; minimum 1000.
API_CREDENTIAL_JAIL_MS	300000	Jail duration in milliseconds; minimum 1000.

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

1. Select the intended team and open Settings → API Keys. Check Available Scopes and the API Keys quota before creating a credential.
2. 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.
3. 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.
4. 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.
5. 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 inspected 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 rely on usage tracking, with asynchronous or best-effort writes; they are not proof that every request succeeded or an exact audit ledger. Requests Today appears only when a daily allowance is truthy. Its displayed day uses the web API 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.