Authentication & scopes

Every request carries a Bearer credential in the Authorization header. Two credential types are accepted:

Credential	Prefix	For
Account API key	`mchp_`	Your own integration with your own account. Created in Settings → Developer.
OAuth 2.1 access token	`mcho_`	Third-party apps acting on behalf of many Merchable accounts.

Authorization: Bearer mchp_…

A missing or invalid credential returns 401 with a WWW-Authenticate challenge; a valid credential without the required scope returns 403.

Scopes

Each key or token carries a set of scopes. Choose the smallest set the integration needs.

Scope	Grants
`account:read`	Read the account profile
`designs:read`	Read designs, their variants, unit prices and stock
`shops:read`	Read shops, their designs and their collections
`orders:read`	Read orders, shipments and order events
`orders:write`	Quote, place and cancel orders
`customers:read`	Read customers and their custom fields
`customers:write`	Create and update customers and their custom fields
`mcp`	Legacy umbrella scope used by MCP chat clients — implies everything

A :write scope implies its :read (orders:write → orders:read, customers:write → customers:read). Every operation in the reference lists the scope it needs. An order-placing integration typically needs designs:read and orders:write.

API keys

Keys are shown once at creation and stored hashed; there is no way to retrieve a lost key — create a new one and revoke the old.
Keys can carry an expiry date. Expired keys return 401 with error="invalid_token".
Revoking a key takes effect immediately.
Keys belong to the member who created them and are limited to the account they were created in. Only account owners can manage keys.

OAuth 2.1 (for apps)

Merchable is an OAuth 2.1 authorization server at https://app.merchable.co. Use it when your app acts for other Merchable accounts — a connector, plugin or agent your customers install. The full walkthrough with request and response examples is in OAuth for third-party apps, and every OAuth endpoint is listed under Third-party apps in the reference. In brief:

Your app's lifecycle

Register once at POST /oauth/register with your name, website, logo, contact email, terms and privacy links, and callback URLs. No approval step: you get a client_id immediately, plus a one-time registration_access_token (and a client_secret for confidential clients, which must supply at least one contact email).
Each of your users connects by approving the consent screen; you hold a token per connected account.
Update your name, website, logo or callbacks any time with PUT /oauth/register/{client_id} using the registration token.
Merchable reviews every registration and may suspend (reversible, grants kept) or revoke (permanent) a client that impersonates a brand, over-requests scopes or is reported by users. Status is returned in the registration and configuration responses.

Protocol

Discovery: https://app.merchable.co/.well-known/oauth-authorization-server
This API's protected-resource metadata: https://api.merchable.co/.well-known/oauth-protected-resource
Flow: authorization code + PKCE (S256) only. Dynamic client registration (RFC 7591) and client configuration (RFC 7592); public (PKCE-only) and confidential (client secret) clients are both supported.
Always send scope. The consent screen shows the user exactly the scopes you requested. A request with no scope is granted the legacy mcp umbrella (full access) and the screen says so — appropriate for AI chat clients, not for an API integration.
The resource parameter (RFC 8707), if sent, may name this API (https://api.merchable.co) or the MCP server (https://app.merchable.co/mcp).
Access tokens live for 1 hour; refresh tokens rotate on use with a 30-day sliding window, and reuse of a rotated refresh token revokes the whole grant. Grants to public clients end 90 days after consent regardless of refreshing; grants to confidential clients have no cap.
Revoke at POST https://app.merchable.co/oauth/revoke (RFC 7009). Users can also disconnect your app at Settings → Developer → Connected apps.
Verified confidential clients can create a Merchable account for a user who has none with POST /v1/partner/accounts (HTTP Basic with the client secret). The user sets a password from the email we send and approves your app on the consent screen; you then receive a code as usual. See Creating accounts for your users in the OAuth guide.

Use the access token exactly like an API key. The same scopes apply, and a missing scope is 403 with the required scope named in detail.