Skip to main content
Every call to the API carries a token in the Authorization header:

​
Create a token

In Settings → API tokens → New token (editor or owner role). The token is shown once only. Details in API tokens and webhooks.

​
What it may do

A read-only token that tries to write gets 403 missing_ability.

​
Live keys and test keys

A token is a live key or, with Test key switched on when it is created, a test key. A test key sends nothing: transactional e-mails are logged and marked sent without reaching a provider, campaign tests are checked and not sent, and nothing counts against the allowance. It reads and writes the team’s real data all the same. See Test keys. GET /v1/me says which one a token is, in sandbox.

​
Which team it works for

A token works for the team it was created in, and for that team only. It sees nothing of its owner’s other teams, even when they switch team in the browser. It also acts with its owner’s rights in that team, checked on every call:
  • if the owner becomes a viewer, writes answer 403 role_not_allowed;
  • if they leave the team, every call answers 403 team_access_lost;
  • if the team requires two-factor authentication and the owner has set up neither a second factor nor a passkey, every call answers 403 two_factor_required, until they do;
  • if the team is suspended, every call answers 403 team_suspended.
For a lasting integration, create tokens from a service account (say api@myshop.example, editor role) rather than from the account of someone who may leave the team.

​
Good habits

  • One token per application. You will know which one to revoke.
  • The least you need. A dashboard that reads statistics only needs Read.
  • Server side only. A token in browser JavaScript or in a mobile application is public. To subscribe from a browser, use the form, which needs no token.
  • In a vault. An environment variable or a secret manager, never in the repository.
  • Revoke at the first doubt: Settings → API tokens → Revoke cuts access immediately. The Last used column helps spot a forgotten token.

​
Authentication answers