> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Astradial API — using API keys, JWT tokens, or internal keys.

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:**

```bash theme={null}
curl -X GET https://your-server:8000/api/v1/calls \
  -H "X-API-Key: ak_1a2b3c4d5e6f7890abcdef..."
```

### Create an API key

1. Go to **API & Webhooks** in the sidebar
2. Click **Create Key**
3. Enter a name and select permissions
4. 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     |

<Note>
  API keys are scoped to your organization. You can only access your own data.
</Note>

## JWT bearer token

For user-level authentication, use a JWT token obtained from the login endpoint.

**Get a token:**

```bash theme={null}
curl -X POST https://your-server:8000/api/v1/auth/user-login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'
```

**Response:**

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "...",
    "email": "user@example.com",
    "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
```

<Warning>
  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.
</Warning>

## 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                                  |