#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.
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
| Role | 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 where the portal exposes it. |
Internal AiDial roles may have operational access when they select an explicit client. Customer roles do not manage partner API keys.
#Creating A Key
When a partner administrator creates an API key, select the client first, then choose:
- scope: Read-only API access or Management API access
- 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 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 inventory
- webhooks
- partner clients
- catalogs, phone numbers, knowledge bases, call control, 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.