Skip to main content

Authentication

Every authenticated request carries the credential in the api_access_token header. There is no OAuth and no Bearer: it is the key value, raw.

curl --request GET \
  --url 'https://app.azchat.digital/api/v1/accounts/1/conversations' \
  --header 'api_access_token: SUA_CHAVE_AQUI'

The three credentials​

The kind of credential determines which endpoints you can reach. The Reference says, on each endpoint, which one is accepted.

userApiKey — user key​

The common one: it covers practically the whole application API (/api/v1/accounts/… and /api/v2/accounts/…). Access follows the permissions of the user who owns the key — a key created by an agent sees what that agent sees.

Where to get it: Settings → API → Create new key.

agentBotApiKey — bot token​

For integrations that reply as a support bot. It reaches only the bot endpoints. Handed out by a system administrator when the bot is created.

platformAppApiKey — platform app token​

For provisioning the installation from outside: creating accounts, users, roles and bots (/platform/api/v1/…). It is the most powerful credential — it operates above accounts, not inside one. Obtained from the system administrator when a platform app is created.

The Client API uses no key​

The endpoints under /public/api/v1/… are meant to run in the contact's browser (it is what the widget uses). They identify themselves with the inbox's public token and the contact identifier, and therefore do not carry an api_access_token. Never put a user key in client-side code.

Scopes are not enforced yet​

When you create a key, the screen offers scopes (Conversations, Contacts, Reports…). They are stored and displayed, but not checked by the server: in practice every key has full access to the account.

That means:

  • ticking scopes does not reduce the risk of a leaked key;
  • do not hand a key to a third party counting on the limitation;
  • if you need restricted access today, create the key with a user whose permissions are already limited — it is the user's permission that counts.

Looking after the key​

  • The key is shown once, at creation. Store it in a secrets vault.
  • Do not commit the key and do not expose it in the front end.
  • Suspect a leak? Delete the key in Settings → API. Deletion takes effect immediately.
  • Prefer one key per integration: that way you can revoke one without taking the others down.