Skip to main content
Version: 2026-05

Authentication

The &Open API authenticates every request with a bearer token. A token identifies the account it was issued for and grants access to that account's data only. A token cannot make cross-account requests.

Your token​

Generate your API token from the admin area of your &Open account: an admin on your team opens the API keys page and chooses Generate new API key. You'll need the admin role to do this; ask a teammate who has it if you don't.

Copy the token as soon as it's shown. &Open displays it once and keeps no retrievable copy, so if you lose it you'll need to generate a new one. Tokens look like this:

ao-v1-{stage}-{secret}

{stage} is the environment the token was issued for (staging or production), and {secret} is an opaque random string. A production token works only against the production base URLs; a staging token works only against staging. See Environments for the base URL of each.

Authenticating a request​

Send the token in the Authorization header, prefixed with Bearer :

Authorization: Bearer ao-v1-production-your_secret_here

A complete request also carries the API version header and, for requests with a body, Content-Type: application/json:

curl "https://api.andopen.co/campaigns" \
  -H "Authorization: Bearer ao-v1-production-your_secret_here" \
  -H "AndOpen-API-Version: 2026-05" \
  -H "Content-Type: application/json"

When authentication fails​

The API rejects a missing, malformed, or unknown token with 401 Unauthorized and an authentication_error:

{
  "errors": [
    {
      "type": "authentication_error",
      "code": "unauthorized",
      "message": "Authentication failed. Provide a valid Bearer token in the Authorization header."
    }
  ]
}

Every one of those cases returns the same unauthorized code, so the response won't tell you which it was. Check the header, the token value, and the region in that order.

Because a token is bound to one account in one region, presenting it to the wrong region also fails with 401 Unauthorized: the token is not recognized there. Send your requests to the base URL for the region your account was provisioned in; see Environments.

The AndOpen-API-Version header is checked before authentication, so a request that omits or misstates the version fails with 400 and an unsupported_api_version error before the token is ever examined. See Versioning for that case, and Errors for the full taxonomy.

Keeping tokens safe​

  • Keep your token secret. Treat it like a password; never commit it to source control or expose it in client-side code.
  • Rotate tokens periodically. Generate a new token, move your integration over to it, then expire the old one. Tokens do not expire on their own.
  • Revoke compromised tokens immediately. Expire any token that may have been exposed from the API keys page; an expired token stops working straight away.