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 :
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:
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:
{
"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.