Authentication

Every v1 endpoint requires an API key. Send it as a bearer token in the Authorization header.

Key format

Keys are 40 characters with a stable prefix:

av_live_ABC123abc456DEF789def012GHI345ghi678

av_live_ — product marker and environment indicator
[A-Za-z0-9]{32} — random body, ~190 bits of entropy

The _live_ segment is present to leave room for a future av_test_ sandbox key. Today all keys are production keys.

Sending the key

Header format:

Authorization: Bearer av_live_********************************

Bearer is case-sensitive — lowercase or mixed-case variants are rejected. Most mainstream HTTP libraries set this correctly; if you're hand-crafting a request, double-check the capitalization.

Don't send the key in query strings or request bodies. Only headers. Query strings end up in browser history, proxy logs, and third-party analytics.

Scopes

Each key is issued with one of two scopes:

`read`

GET endpoints only. Safe for reporting, analytics, dashboards. Cannot create, update, or delete anything.

`read, write`

Everything read can do, plus POST, PUT, PATCH, DELETE on allowed resources. Treat with the same care as an admin dashboard session.

If a write-scope endpoint is called with a read-only key, the response is:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":"insufficient_scope","required":"write"}

Rotating and revoking

All key management happens in the dashboard. There is no API endpoint to generate or revoke keys (that would be a chicken-and-egg problem) — sign in at Settings → API Keys.

Rotate: generate a new key, update your integration to use it, revoke the old one. There's no downtime — both keys work until the old one is revoked.
Revoke: click the trash icon. The next request using that key gets a 401.

Revocation is immediate. There's no "soft" revocation or grace period.

Malformed key responses

All authentication failures return the same 401 with a uniform body — no information about which check failed:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"unauthorized"}

Common causes, in rough order of frequency:

Key is revoked
Authorization header missing or typo (bearer lowercase, etc.)
Key value is truncated during copy-paste
Wrong organization — the key is valid but for a different org than you expect

Best practices

Use environment variables. Never commit keys to source control. Most CI/CD systems have a secrets store — use it.
Give each integration its own key. One for Zapier, one for analytics ETL, one for your custom app. Revoking one doesn't break the others.
Use read-only keys where possible. A reporting script doesn't need write access. Smaller blast radius if compromised.
Rotate periodically. Quarterly is a reasonable cadence. More often if a team member with access leaves.
Confirm scope in responses. The GET /v1/me endpoint echoes back your org, key name, and scopes — useful for sanity checks in deployment pipelines.