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

# AuditRails API Authentication: Bearer Tokens & Keys

> Authenticate every AuditRails API request with a Bearer token. Learn key types, security best practices, and how to handle auth errors.

Every request to the AuditRails API must be authenticated using an API key passed as a Bearer token in the `Authorization` header. Keys are scoped by environment — live keys write to your production audit chain and count against your plan limits, while test keys use a separate free-tier pool and are safe to use during development and CI.

## Obtaining an API Key

You create and manage API keys from your AuditRails dashboard. Keys are displayed **only once** at creation time and are stored as a one-way hash — if you lose a key, revoke it and create a new one.

**Dashboard → API Keys → Create API Key**

<Warning>
  Copy your API key immediately after creation. AuditRails cannot show it to you again after you close the creation dialog. Store it in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault) and never commit it to source control.
</Warning>

***

## Key Types

AuditRails issues two distinct key prefixes with different behaviors:

| Prefix     | Environment    | Rate Limit             | Plan Usage               | Recommended For         |
| ---------- | -------------- | ---------------------- | ------------------------ | ----------------------- |
| `at_live_` | Production     | 1,000 req/s (default)  | Yes — counts toward plan | Production applications |
| `at_test_` | Test / sandbox | 60 req/s (shared pool) | No — always free         | Local dev, CI pipelines |

<Warning>
  Never use `at_test_` keys to handle production traffic. The test-key pool is shared across all customers and is not covered by uptime SLAs.
</Warning>

***

## Sending the Authorization Header

Pass your API key as a Bearer token in every request:

```bash theme={null}
curl -X POST https://api.auditrails.io/v1/events \
  -H "Authorization: Bearer at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "user.login",
    "actor_id": "user_123"
  }'
```

The header must be formatted exactly as shown — the word `Bearer` (capital B), a single space, then your key. No other authentication schemes (Basic, API-Key header, query-string tokens) are accepted.

***

## Authentication Errors

All authentication failures return HTTP `401 Unauthorized` with a structured error body. The `code` field tells you exactly what went wrong:

| Error Code            | Cause                                          | Resolution                                                                             |
| --------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| `auth/missing_header` | `Authorization` header not present.            | Add `Authorization: Bearer <key>` to every request.                                    |
| `auth/invalid_format` | Header present but not in `Bearer <key>` form. | Check for extra spaces, missing `Bearer` prefix, or encoding issues.                   |
| `auth/key_not_found`  | Key does not exist in AuditRails.              | Verify you copied the key correctly; create a new key if needed.                       |
| `auth/key_revoked`    | Key has been manually revoked.                 | Generate a replacement key from the dashboard.                                         |
| `auth/key_expired`    | Key has passed its expiry date.                | Rotate to a new key; consider setting a longer expiry or no expiry on the replacement. |

**Example 401 response:**

```json theme={null}
{
  "error": {
    "code": "auth/key_revoked",
    "message": "This API key has been revoked and can no longer be used.",
    "request_id": "req_01HX7YGBFZ3QK8N9VMJT5RPCE4",
    "doc_url": "https://docs.auditrails.io/reference/error-codes"
  }
}
```

<Note>
  The `request_id` in every error body matches the `X-Request-Id` response header. Include it when contacting AuditRails support — it lets the team look up the exact request in server-side logs.
</Note>

***

## Security Best Practices

* **Rotate keys regularly.** Use the dashboard to revoke old keys and issue new ones on a schedule that fits your security policy.
* **Use separate keys per service.** Issuing one key per application or microservice limits blast radius if a key is compromised.
* **Set expiry dates.** For short-lived jobs (e.g. batch migrations), create a key with a tight expiry window.
* **Never expose keys client-side.** API keys must only be used from server-to-server calls. If you need to log events from a browser, proxy requests through your own backend.
* **Monitor for unexpected usage.** The AuditRails dashboard shows per-key request counts — an unusual spike can indicate a leaked key.