Authentication

API keys

Agency owners create keys in the dashboard under API. API access is included in the Premium and Agency plans while the subscription is current (including while a failed payment is retried, and until the end of the paid period after cancelling), and during your trial.

• The full key (aa_live_...) is shown once, when you create it. Store it in an environment variable or secret manager on your server.
• Create one key per integration, so each can be revoked on its own.
• Never put a key in browser or mobile code. Your server calls the API; browsers only get the links it returns.

Making calls

Send the key in the Authorization header as a bearer token. To check a key, call GET /me: it returns the key's agency and scopes and needs no scope itself.

curl "https://api.agencyaccess.co/api/v2/me" \
  -H "Authorization: Bearer $AGENCYACCESS_API_KEY"

{
  "data": {
    "agency": {
      "id": "0b3e5f7a-1c2d-4e6f-8a9b-0c1d2e3f4a5b",
      "name": "Acme Marketing"
    },
    "apiKey": {
      "id": "9e8d7c6b-5a49-4382-a1b0-c9d8e7f6a5b4",
      "scopes": [
        "clients:read",
        "clients:create",
        "requests:read",
        "requests:create"
      ]
    }
  },
  "meta": {
    "requestId": "req_1f0b6c2e9a7d4f58b3c1e6a9d2f4b7c0"
  }
}

Scopes

Each key has the scopes chosen when it was created. A call that needs a scope the key lacks returns 403 CAPABILITY_REQUIRED, naming the scope. Each endpoint in the reference lists the scope it needs.

To change a key's scopes, create a new key with the scopes you need and revoke the old one.

Rotating and revoking keys

Keys do not expire. To rotate one, create a new key, deploy it to your integration, then revoke the old key in the dashboard. A revoked key is rejected immediately. If a key may have been exposed, revoke it right away.

Authentication errors