Skip to main content
Every API request — except GET /v1/health — must include your API key. Two header schemes are accepted:
Most direct API consumers use Authorization: Bearer. The X-API-Key header exists for gateway integrations (Smithery, Zapier, Make, n8n) that reserve the Authorization header for their own use. If both are present, Authorization wins.

​
Key format

Validation regex: ^al_(live|test)_[a-zA-Z0-9]{32}$ Keys are stored as a SHA-256 hash. AcreLens cannot recover a lost key — if you misplace it, revoke and replace.

​
Live vs test environments

Both environments hit the same routes and return the same shape. The differences are about what gets tracked:
Note: Test keys still consume your balance — they’re a guardrail against committing live keys to source control, not a free sandbox. Use free trial reports for cost-free experimentation.

​
Where keys come from

When you verify your account, AcreLens creates one live key and one test key automatically. To create more, open Manage → API Keys, click + New key, label it, and pick an environment. The full key is displayed exactly once. Copy it to a secret manager (1Password, AWS Secrets Manager, Doppler, Vercel env vars) before closing the modal.

​
Rotating keys

Zero-downtime rotation:
  1. Create a new key labeled with today’s date (e.g. Production — 2026-04-28).
  2. Deploy the new key to your application.
  3. Once your service has fully rolled over, revoke the old key from Manage → API Keys.
Revoked keys return 401 unauthorized immediately on the next request — there’s no grace period. Plan the cut-over so both keys are valid for the few minutes your deploy takes.

​
Authorization errors

Any of the following return 401 unauthorized:
  • Missing both Authorization and X-API-Key headers
  • Authorization header doesn’t start with Bearer
  • Token doesn’t match the format regex
  • Token is unknown (never created or fully purged)
  • Token has been revoked
Both error and success responses include a request_id you can quote when contacting support.
Only accounts in ACTIVE or TRIAL status can transit a valid key. Any other status (e.g. CANCELED, PAST_DUE) returns 403 forbidden regardless of key validity. Update billing in the Billing section or contact support. REST API access is a Pro-plan feature. A key belonging to a Free or Starter subscription account is rejected with 403 api_access_required; upgrade to Pro to use the API. (Legacy pay-as-you-go accounts keep API access.)

​
Security checklist

  • Store keys in environment variables — never commit them to source control.
  • Use a secret manager for production keys (1Password, AWS Secrets Manager, Doppler).
  • Rotate keys when team members leave or after any suspected exposure.
  • Use separate keys per environment and per service (label them descriptively).
  • Treat al_test_ keys with the same care as live keys — they still bill against your account.