Authentication

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

Example:

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"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "...",
    "email": "[email protected]",
    "role": "admin"
  }
}

Use the token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT tokens expire after 24 hours.

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

Getting started

Calls

Resources

API key authentication (recommended)

Create an API key

API key permissions

JWT bearer token

Internal API key (server-to-server)

Response codes

​API key authentication (recommended)

​Create an API key

​API key permissions

​JWT bearer token

​Internal API key (server-to-server)

​Response codes

API key authentication (recommended)

Create an API key

API key permissions

JWT bearer token

Internal API key (server-to-server)

Response codes