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

# Authentication

> Authenticate Public REST API requests and interpret authentication errors.

Create a key from **Settings > Developer** when API key management is available to your account. The full key is displayed once after creation or regeneration. Store it on your server in a secret manager or protected environment variable.

## Request Headers

Use one of these headers with requests to your deployment's `/api/v1` endpoints:

```http theme={"theme":{"light":"min-light","dark":"min-dark"}}
Authorization: Bearer YOUR_CALLGENCY_API_KEY
```

Alternatively:

```http theme={"theme":{"light":"min-light","dark":"min-dark"}}
X-API-Key: YOUR_CALLGENCY_API_KEY
```

These are placeholders, not usable credentials. If both headers are sent, a Bearer authorization header takes precedence. Account login sessions and API keys are separate credentials; API key management uses your signed-in dashboard session.

## Permissions and Restrictions

Each key has scopes that permit specific operations. An endpoint can reject a valid key if it lacks the required scope or its IP whitelist excludes the caller. Inactive, deleted, regenerated, or expired keys cannot authenticate with the old secret.

| HTTP status | Error code | What to check |
| - | - | - |
| 401 | `UNAUTHORIZED` | Supply an API key in a supported header |
| 401 | `INVALID_API_KEY` | Check the secret, key status, and any expiry; update clients after regeneration |
| 403 | `IP_NOT_WHITELISTED` | Check the key's configured server IP addresses |
| 403 | `INSUFFICIENT_SCOPES` | Check the endpoint's required scope and the key's permissions |
| 429 | `RATE_LIMIT_EXCEEDED` | Wait before retrying; inspect rate-limit information in the response |

The response includes `X-Request-ID`, and structured errors include `meta.requestId`. Keep this ID when reporting an error. Other endpoint-specific validation or access errors can also occur after authentication.

See [API Security](https://docs.callgency.ai/api-reference/security.md) for key handling and request limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.