#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
| Use case | Authentication |
|---|---|
| A signed-in partner using the AiDial Portal | Portal session; the portal server calls the AiDial API with a bearer token. |
| A trusted partner server calling the AiDial API directly | X-API-Key header sent from the server-side system. |
If both X-API-Key and Authorization: Bearer are sent to the AiDial API, the API key is evaluated first. Portal browser calls should not send either header directly.
The portal's API-key screens use same-origin BFF routes under /api/partner/api-keys/**. Those route handlers validate the signed-in next-auth/Zitadel session, enforce role access and CSRF on mutations, require a server-validated selected client, then call aidial_api with the server-side bearer token. Portal BFF routes are not direct integration contracts.
See API Authentication for the authentication model. Your AiDial contact will provide the maintained API reference for 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.
| Role | Portal access |
|---|---|
partner_admin | View API-key metadata, create new API keys, rotate active keys, and revoke active keys for assigned clients. |
partner_user | View API-key metadata in read-only mode for assigned clients where the portal exposes it. |
aidial_admin | Operationally view, create, rotate, and revoke API keys when an explicit client is selected. |
aidial_operator | Operationally view API-key metadata in read-only mode when an explicit client is selected. |
Customer roles do not manage partner API keys. Out-of-scope, missing, archived, or unassigned selected clients return non-enumerating errors before the portal forwards the request to aidial_api.
#Creating A Key
When a partner administrator creates an API key, select the client first, then choose:
- scope: Read-only API access (
partner_user) or Management API access (partner_admin) - description
- optional expiry date
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
#Rotating A Key
Rotation creates a replacement key, preserves the source key's scope, and immediately disables the current key.
- Open the selected client's API-key inventory.
- Choose Start Rotation on the active key.
- Confirm the rotation.
- Store the replacement key shown once.
- 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. Current public API reference material covers:
- authentication and error semantics
- rate limiting
- project lifecycle and publish/version endpoints
- partner identity
- API-key metadata and bearer-session lifecycle routes
- webhooks
- partner clients
- catalogs, phone numbers, knowledge bases, call control, batch calls, outbound compliance, outbound campaigns, and billing where enabled
Use the maintained AiDial API reference supplied by your AiDial contact for request and response shapes. Portal-only routes are not direct integration contracts.