AuditRails API Authentication: Bearer Tokens & Keys

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

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.

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

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.

Sending the Authorization Header

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

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:

{
  "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"
  }
}

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.

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.

Overview

Ingestion

Read & Verify

Data Subject Requests

AuditRails API Authentication: Bearer Tokens & Keys

Obtaining an API Key

Key Types

Sending the Authorization Header

Authentication Errors

Security Best Practices

​Obtaining an API Key

​Key Types

​Sending the Authorization Header

​Authentication Errors

​Security Best Practices

Obtaining an API Key

Key Types

Sending the Authorization Header

Authentication Errors

Security Best Practices