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 |
mcp |
Legacy umbrella scope used by MCP chat clients — implies everything |
orders:write implies orders: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
401witherror="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:
- 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). Public clients only; dynamic client
registration (RFC 7591) at
/oauth/register. - Request scopes with the
scopeparameter (space-separated). The user approves them on the consent screen. - Access tokens live for 1 hour; refresh tokens rotate on use and live for 30 days.
- Revoke at
POST https://app.merchable.co/oauth/revoke(RFC 7009).
Use the access token exactly like an API key.