Skip to content

Authentication

Account and business API tokens, how to create and revoke them, what they reach and how a call is refused.

Updated

Every call carries an API token as a bearer:

Authorization: Bearer ucn_...

There are two kinds of token:

  • Account tokens (ucn_...) are personal: they act as the seller who created them, in each business they picked, on all or some of its stores. In each business a call may do what both that seller’s seat and the token allow, checked on every call, so a token never does more than its seller can do in the merchant app right now.
  • Business tokens (btk_...) belong to the business and act as no one. They keep working when the people who made them leave, so they suit integrations the business relies on. See business tokens.

Create a token

Account tokens are created in the merchant app, never through the API: open Account settings, then API tokens, and choose New token.

  • Name: what uses it, so you know what breaks if you revoke it.
  • Expires: after one of the periods the form offers, or never. An expired token stops working; make a new one.
  • Businesses: each business it reaches, and in each, every store (including ones added later) or only the stores you pick.
  • Access: in each business, what it may do there, which comes down to scopes. You can give only what you may do yourself in that business.

The token is shown once, right after you create it: copy it then, since nobody can see it again. Its name, expiry, businesses, stores and access stay as created, so make a new token to change them. Each business it reaches has its own limits, a rate (calls a minute) and a quota (calls a day or a month) that apply on each store on its own: the default rate and no quota until you change them on the API tokens page. See rate limits.

Your tokens are yours alone: other members of a business only see that one of yours reaches it. A seller holds at most 100 working tokens at once.

A business decides who may point tokens at it

A token reaches a business only while your seat there allows managing API tokens: you need it to pick the business, and the token keeps checking it on every call. Taking that permission away stops your tokens in that business at once, while they keep working in the others; giving it back brings them back. So a business that wants no personal tokens pointed at it gives no one that permission, and uses business tokens instead.

Tokens made before account tokens could reach several businesses start with utk_. They keep working, each reaching its one business, and become account tokens with the same bearer: from then on they are listed with your other account tokens and follow the rules above.

Business tokens

A business token belongs to the business, not to a seller. Only members who may manage API tokens in the business make, edit and revoke them; the owner may, and can let other members too. Every member who may see API tokens sees the business’s tokens, with who made each, who last edited it and who revoked it.

  • Access: the permissions it gets, which are scopes, and never more than the member making or editing it holds then. An edit by a member who holds less narrows the token to what they hold. A business token never holds the apitoken scopes.
  • Stores: every store of the business, including ones added later, or only the stores you pick.
  • Limits and expiry: as for an account token, set when it is made. Limits apply on each store on its own.

After that it stands on its own: a member who made or edited it leaving the business, or closing their account, changes nothing. It is shown once, right after it is made; its name, access, stores, limits and expiry can all be changed later.

A business token works over this API alone, on store operations: the operations under /v1/merchants speak for a seller and answer 403 with the reason principal. Read business on a store it reaches lists the business’s stores it may act on. It never acts on the business’s billing, payouts or profile, which only members change. What it writes is recorded under token:<id>, the token’s id, where a seller’s id would be, such as a grant’s granted_by. The business holds at most 100 working business tokens at once.

Anyone who may manage API tokens in the business may revoke a business token, even while the business is suspended: it stops working at once, and what it set up is turned off as for an account token below. An edit that takes away scopes or stores, or brings its expiry closer, turns off what it set up that it no longer could.

What a token reaches

  • Its businesses and stores. An account token reaches the businesses it was given, each on every store or on the stores picked there; a business token reaches its own business, on every store or on some. Both work over this API alone: the merchant MCP server takes the connection you approve when an app signs in to it.
  • Stores by id. Store operations take the store’s id in the path, /v1/stores/{store}, and act on that store’s business with what the token may do there. A store the token doesn’t reach answers 403 with the reason principal, exactly like one that does not exist, so a token can’t learn which stores exist elsewhere.
  • The businesses themselves. For an account token, GET /v1/merchants lists every business the token reaches and the stores it may act on in each, whatever it may do there, so a token can always find where it works; GET /v1/merchants/{merchant} reads one’s details and plan, and needs organization:read in that business. A business token reads its business, with the stores it may act on, through Read business on a store it reaches, which needs organization:read.

Refusals

Answer When
401, WWW-Authenticate: Bearer No Authorization header.
401, WWW-Authenticate: Bearer error="invalid_token" The header isn’t a bearer token, or the token is unknown, expired or revoked as a whole. Signing in again won’t help: create a new token.
403, WWW-Authenticate: Bearer error="insufficient_scope" The token lacks the scope the operation needs. The reference names each operation’s scope.
403 with the reason principal The token may not act on this store or row: a store outside its businesses or its stores, a business it no longer works in (its seller left it, lost the permission to manage API tokens there, or removed the token from it), a file URL another token asked for, or, for a business token, an operation only a seller may call. Its other businesses keep working.
403 with the reason plan The store’s plan doesn’t include what the call asks for.

Each refusal’s body is a problem whose context.reason says which. A token is never taken from the query string.

Revoke a token

Revoke an account token on the same API tokens page, or remove it from one business alone. Anything using it stops working right away, everywhere or in that business, and the webhook endpoints, integrations and redirects it set up there are turned off; this can’t be undone. Access it granted and affiliates it made or changed stay until you end them, and automations it created keep running until you pause them. The page lists them when you revoke it, and shows each token’s last use.

Keep tokens safe

  • Store a token as a secret, never in code, a repository or a URL.
  • Give each script its own token with only the scopes it needs, so revoking one breaks nothing else.
  • Prefer a token that expires, and make a new one before it does.
  • Use a business token for an integration the business relies on, so it outlives any one member’s access.
  • Call the API from a server, never from a browser or an app your customers run: an account token acts as you, and a business token for your business. To build a storefront, use the customer API instead.

Type to search…

↑↓ navigate↵ selectEsc close