#API Keys & Partner API

Use API keys for trusted server-side partner integrations that call the AiDial API directly. Do not use API keys in browser code, client-side JavaScript, mobile apps, or screenshots.

#Portal Session Versus Direct API Key

Send only one credential per request. If both X-API-Key and Authorization: Bearer are sent to the AiDial API in the same request, the API key is used and the bearer token is ignored. Portal browser calls should not send either header directly; if a browser does attach X-API-Key to an API-key portal route, the portal strips it before forwarding upstream and still authenticates with the signed-in session.

In the portal, API-key management is the API Keys tab of the Integrations page, and it is the tab that opens by default. Those screens use same-origin BFF routes under /api/partner/api-keys/**. Those route handlers validate the signed-in portal session, enforce role access and CSRF on mutations, require a selected client, then call aidial_api with the server-side access token. Portal BFF routes are not direct integration contracts.

See API Authentication for the authentication model and Partner Integrations for API-key request and response details.

#Who Can Manage API Keys

API-key lifecycle management is a portal bearer-session workflow. Direct X-API-Key callers may read scoped metadata where the API reference enables it, but they cannot create, rotate, or revoke API keys.

These roles are enforced in the portal route handlers, not only in the interface: the read route accepts partner and internal roles, and the create, rotate, and revoke routes accept only partner_admin and aidial_admin. Mutations also require the portal CSRF check.

Customer roles do not manage partner API keys. Every API-key route needs a selected client: if none is supplied, the portal returns a non-enumerating error before it forwards anything to aidial_api. For partner roles the portal also checks the selected client against your assignments and rejects unassigned, archived, and deleted clients the same way. Out-of-scope clients selected by an internal role are rejected by aidial_api with the same non-enumerating error.

#Creating A Key

When a partner administrator creates an API key, select the client in the Integrations page header, then choose:

• scope: Read-only API access (partner_user) or Management API access (partner_admin)
• description, up to 256 characters
• optional expiry date; the picker only accepts today or a later date

Each key is issued for one client and one data environment, and it is only listed, rotated, or revoked in the environment it was issued for. That environment comes from your signed-in session, not from the Environment selector in the Integrations page header; that selector scopes the Webhooks and SCIM tabs, and leaves the API Keys tab unchanged.

The plaintext key is shown only once after creation. Store it immediately in your server-side secrets manager. After that moment, the portal and API inventory show metadata only.

Do not store API keys in:

• source code
• browser storage
• build logs
• issue trackers
• chat messages
• screenshots
• client-side apps

#Reviewing Keys

The API Keys tab splits the selected client's keys into Active and Revoked lists. A key is shown as Active, Revoked, or Expired; a key past its expiry date is shown as Expired and appears in the Revoked list. Revoked and expired keys that share the same label are collapsed under one heading for historical review.

Each key shows its scope and environment, when it was created, when it expires, when it was last used, and a revocation field. The key list never carries a revocation timestamp, so that field reads Revoked for a revoked key and Not revoked for any other key, never a date. Rotate and revoke actions appear only on active keys, and only for roles that can manage them.

#Rotating A Key

Rotation creates a replacement key and immediately disables the current key. The replacement keeps the source key's scope and expiry date, and is labelled as the replacement for the rotated key.

1. Open the API Keys tab on the Integrations page and select the client.
2. Choose Start Rotation on the active key.
3. Choose Confirm Rotation.
4. Store the replacement key shown once.
5. Update the trusted server-side integration to use the replacement key.

Only rotate when you are ready for the current key to stop working immediately.

#Revoking A Key

Revocation permanently disables the key. It cannot be reactivated. Revoke a key when:

• it is no longer used
• it may have been exposed
• a partner user or integration no longer needs the same scope
• rotation has completed

If a key may have been exposed, treat the incident as urgent and follow Escalation Boundaries.

#Direct API Usage

Direct partner API calls use the base URLs supplied by AiDial. The published AiDial API reference covers:

• authentication, credential precedence, and error semantics
• rate limiting and the deprecation policy
• partner identity, API-key metadata, webhooks, model and voice catalogs, and capacity
• project lifecycle, assignments, and publish/version endpoints
• calls analytics, outbound campaigns, compliance caller requests, and billing
• health and status endpoints

API-key lifecycle mutations are not part of the direct X-API-Key surface. Create, rotate, and revoke require a portal bearer session and an Idempotency-Key header, and create and rotate are rate limited. Direct API-key callers may list key metadata for their own client and may omit client_id; when they supply it, it must match the key's own client. Bearer callers must name the target client on every API-key route.

Use the API reference for request and response shapes. Portal-only routes are not direct integration contracts.

#Related Pages

• Integrations
• Projects
• Error Responses
• Tenant Scoping