Authentication
Send a seller's API token as a bearer: Authorization: Bearer ucn_.... A seller creates tokens on the merchant app's API tokens page, picking the businesses it reaches, all or some stores in each, and what it may do in each; in every business a call may do what both the seller's seat there and the token allow, checked on every call.
Store operations live under /v1/stores/{store}, where {store} is the store's id, and act on that store's business with that business's access; GET /v1/merchants lists every business the token reaches, with the stores it may act on. A store the token doesn't reach answers 403 with the reason principal, exactly like one that does not exist. Losing one business (the seller left it, lost the permission to manage API tokens there, or removed the token from it) answers 403 with the reason principal on its stores alone, while the others keep working. Tokens made before tokens reached several businesses start with utk_ and keep working, each on its one business.
A business may instead hold its own token, made by a member who may manage API tokens there: Authorization: Bearer btk_.... It acts as no seller, with the scopes and stores picked for it, and keeps working when its maker leaves. It works on store operations alone: /v1/merchants speaks for a seller and answers 403 with the reason principal, and reading the business on a store it reaches lists the stores it may act on.
A request without a token answers 401 with WWW-Authenticate: Bearer. An unknown, expired or revoked token, or one used where it is not bound, answers 401 with WWW-Authenticate: Bearer error="invalid_token". A token lacking a scope answers 403 with error="insufficient_scope". Each operation in the reference names the scope it needs.