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

# API Key Authentication for the Zexa REST API Requests

> Generate an API key in the Zexa dashboard and pass it as a Bearer token header to authenticate every request made to the Zexa REST API.

Every request to the Zexa REST API must be authenticated. Zexa uses API keys passed as Bearer tokens in the `Authorization` header. There are no sessions or cookies — each request is independently authenticated, making it safe and straightforward to use the API from any server-side environment.

## Generate an API Key

Create a dedicated API key for each application or environment that needs access to the Zexa API. This makes it easy to revoke access for a single integration without affecting others.

<Steps>
  <Step title="Log in to your dashboard">
    Go to [https://app.zexa.ao](https://app.zexa.ao) and sign in to your account.
  </Step>

  <Step title="Open API Keys settings">
    Navigate to **Settings → API Keys** from the left sidebar.
  </Step>

  <Step title="Create a new key">
    Click **New API Key** in the top-right corner of the page.
  </Step>

  <Step title="Name and generate the key">
    Enter a descriptive name for the key — for example, `Production` or `Staging Backend` — then click **Generate**.
  </Step>

  <Step title="Copy the key immediately">
    Your new API key is displayed **only once**. Copy it now and store it somewhere secure, such as a password manager or secrets vault. You will not be able to view it again after closing the dialog.
  </Step>
</Steps>

## Pass Your API Key

Include your API key in the `Authorization` header of every request using the `Bearer` scheme:

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.zexa.ao/v1/credits \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.zexa.ao/v1/credits",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )

  print(response.json())
  ```
</CodeGroup>

## Check Your Credit Balance

Use `GET /credits` to verify that your API key is valid and to retrieve your current credit balance:

```text theme={null}
GET https://api.zexa.ao/v1/credits
```

A successful response returns your current balance:

```json theme={null}
{
  "credits": 4250,
  "currency": "USD"
}
```

<ResponseField name="credits" type="integer">
  The number of message credits remaining on your account.
</ResponseField>

<ResponseField name="currency" type="string">
  The currency in which credits are denominated (e.g. `USD`).
</ResponseField>

For a full breakdown of your credit usage and purchase history, visit the [Credits](/account/credits) page in your dashboard.

## Key Security Best Practices

Treat your API keys with the same care as passwords. A leaked key gives anyone full access to your Zexa account, including the ability to send messages and incur charges.

* **Use environment variables** — store keys in environment variables like `ZEXA_API_KEY` rather than hardcoding them in your source files
* **Separate keys per environment** — use different keys for development, staging, and production so a leaked dev key cannot affect production
* **Revoke unused keys** — delete keys for integrations you no longer use to reduce your attack surface
* **Rotate keys periodically** — generate new keys on a schedule (e.g. quarterly) and update your applications accordingly

<Warning>
  Never commit API keys to version control or share them in public channels such as GitHub, Slack, or support tickets. If a key is accidentally exposed, revoke it immediately and generate a replacement.
</Warning>

<Tip>
  Use environment variables to inject keys at runtime. For example, in Python: `api_key = os.environ["ZEXA_API_KEY"]`. Most deployment platforms (Railway, Render, AWS, etc.) have a built-in secrets management interface for setting environment variables securely.
</Tip>

## Revoke a Key

To revoke an API key:

1. Go to **Settings → API Keys** in your dashboard
2. Find the key you want to revoke
3. Click **Revoke** next to the key name and confirm the action

Revocation is **immediate** — any request using the revoked key will receive a `401 Unauthorized` response. Make sure to replace the key in all your applications before revoking it to avoid service interruption.

## Authentication Errors

<Expandable title="401 Unauthorized">
  The API key is missing, malformed, or has been revoked. Check that:

  * The `Authorization` header is present on the request
  * The header value follows the format `Bearer YOUR_API_KEY` exactly (note the space after `Bearer`)
  * The key has not been revoked in your dashboard
</Expandable>

<Expandable title="403 Forbidden">
  The API key is valid but does not have permission to perform the requested action. This can occur if your account plan does not include a particular feature. If you receive a `403` unexpectedly, contact support at [suporte@zexa.ao](mailto:suporte@zexa.ao) with the `request_id` from the error response.
</Expandable>