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.

There are two kinds of bearer token:

  • An API key is for your own integration with your own &Open account. An admin generates it, and it acts for the whole account. Most integrations use one, and the rest of this page describes it.
  • An OAuth access token is for a partner app that other &Open customers connect to their accounts, such as a CRM integration. Each customer authorizes the app, and the token acts within what they authorized. See OAuth.

You send both the same way, in the Authorization header.

Your token​

Generate your API token from the API keys & webhooks page under Integrations in your &Open account: an admin on your team opens it and chooses Create 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: live for production, or staging. {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 :

Request header
Authorization: Bearer ao-v1-live-your_secret_here

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

Terminal
curl "https://api.andopen.co/campaigns" \
-H "Authorization: Bearer ao-v1-live-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:

Response · 401
{
"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. The one exception is an OAuth access token issued for a different API, which returns invalid_audience; see Common pitfalls.

Every 401 also carries a WWW-Authenticate header. An API key integration can ignore it; an OAuth client uses it to find the authorization server, as Discover the authorization server describes.

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 & webhooks page; an expired token stops working straight away.