The Astradial API supports three authentication methods depending on your use case.
API key authentication (recommended)
The simplest way to authenticate. Create an API key from the dashboard and include it in every request.
Header format:
X-API-Key: ak_your_api_key_here
curl -X GET https://your-server:8000/api/v1/calls \
-H "X-API-Key: ak_1a2b3c4d5e6f7890abcdef..."
Create an API key
- Go to API & Webhooks in the sidebar
- Click Create Key
- Enter a name and select permissions
- Copy the key immediately — it is only shown once
API key permissions
Each key can have specific permissions:
| Permission | What it allows |
|---|
calls.read | Read call logs |
calls.write | Manage calls |
calls.click_to_call | Initiate click-to-call |
calls.originate_ai | Originate calls to AI agents |
calls.recording | Access call recordings |
calls.live | View live calls |
calls.transfer | Transfer active calls |
calls.hangup | Hang up active calls |
calls.hold | Hold/unhold active calls |
API keys are scoped to your organization. You can only access your own data.
JWT bearer token
For user-level authentication, use a JWT token obtained from the login endpoint.
Get a token:
curl -X POST https://your-server:8000/api/v1/auth/user-login \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "your-password"}'
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "...",
"email": "[email protected]",
"role": "admin"
}
}
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Internal API key (server-to-server)
For internal service communication between your own services and Astradial. This bypasses organization-level auth.
X-Internal-Key: your-internal-api-key
The internal API key has full access to all organizations. Only use it for trusted server-to-server communication. Never expose it in client-side code.
Response codes
| Code | Meaning |
|---|
200 | Success |
201 | Created |
400 | Bad request — check your parameters |
401 | Unauthorized — invalid or missing credentials |
403 | Forbidden — insufficient permissions |
404 | Not found |
409 | Conflict — duplicate resource |
500 | Server error |
