Authentication

Send a seller's API token as a bearer: Authorization: Bearer utk_.... A seller creates tokens on the merchant app's API tokens page, picking its scopes; a call may do what both the seller's seat and the token allow.

A token belongs to one business. Store operations live under /v1/stores/{store}, where {store} is the store's id; GET /v1/merchants lists the business a token belongs to and the stores it may act on. A store outside that business answers 403 with the reason principal, exactly like one that does not exist.

A request without a token answers 401 with WWW-Authenticate: Bearer. An expired or revoked token, one used where it is not bound, or one whose seller left the business, 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.