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

# Authentication

> How to authenticate requests to the DialNexa API with Bearer API keys and understand v1 endpoint access.

DialNexa API requests use a Bearer API key in the `Authorization` header. The key identifies your workspace and authorizes access to endpoints that are available to API clients.

## API keys

Create and manage API keys in the DialNexa dashboard under **Settings > API Keys**. An API key has two parts separated by a colon. The full value must be sent as the Bearer token.

```text theme={null}
Example: abcdefghijklmn:123456a1b1234b
```

The segment before the colon is the key ID. The segment after the colon is the secret. Treat the full key like a password. Do not commit it to source control or expose it in browser code.

## Send the Bearer token

Pass the API key in the `Authorization` header on every API-key request.

```bash theme={null}
curl https://api.dialnexa.com/v1/voices \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A missing, revoked, or malformed key returns `401 Unauthorized`.

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}
```

## Endpoint access

The v1 reference includes endpoints exported from the backend with the explicit `V1` Swagger tag and documented under **Endpoints - v1**. These documented v1 endpoints are intended for Bearer API-key access.

| Access type    | Endpoints                                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bearer API key | Agents, calls, batch calls, workflows and workflow leads, user webhooks, voices, languages, LLMs, transcribers including fallback transcribers, knowledge-base create/read/update/delete, and phone-number list/get/search/purchase/SIP-trunk/delete operations. |
| Legacy only    | Endpoints listed only under **Endpoints - Legacy**. Keep existing integrations on those paths until a v1 page is published.                                                                                                                                      |

## Common mistakes

* Sending only the key ID instead of the full `key_id:secret` value.
* Using `x-api-key` instead of the Bearer `Authorization` header for v1 endpoints.
* Assuming a legacy page has a v1 equivalent when it is not listed under **Endpoints - v1**.

## Key management best practices

* Use one key per environment, such as development, staging, and production.
* Rotate keys on a schedule and immediately after suspected exposure.
* Store keys in environment variables or a secrets manager.
* Remove unused keys from the dashboard.

## Webhook signature verification

Incoming webhook payloads from DialNexa are signed with HMAC-SHA256 using the secret configured for that webhook. Verify the `x-dialnexa-signature` header before trusting the payload.

```python theme={null}
import hmac
import hashlib

def verify_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)
```

```typescript theme={null}
import * as crypto from "crypto";

function verifyWebhook(
  payloadBody: Buffer,
  signatureHeader: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payloadBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}
```