Authentication

Every request to /v1/** must include an Authorization: Bearer <key> header. Mercel accepts two credential types — both are sent the same way; the prefix tells the server which kind it is.

API keys

Authorization: Bearer mercel_sk_…

API keys are bound to a single store and issued from the dashboard under Developers → API keys. They can read and write the bound store's resources. Revoking a key invalidates it immediately. Default rate limit: 300 requests / minute.

curl https://api.mercel.app/v1/products \
  -H "Authorization: Bearer mercel_sk_test_…"

Personal access tokens

Authorization: Bearer mercel_pat_…

Personal access tokens represent a user across every organization and store they belong to. Issue them from Account → API keys and use them for CLI tools, scripts, and dashboards.

• Inherits the user's role in the bound store. A PAT can do whatever the authenticated user can do — Owner and Admin can read and write; Viewer is read-only. Requests that exceed the user's role return 403.
• Store binding comes from the URL path on store-scoped routes (/v1/stores/{storeId}/...); the user must be a member of storeId or the request returns 403.
• On routes that don't carry a store id in the path (e.g. /v1/products), send the Mercel-Store-Id: str_… header to scope the request. If both the path and the header name a store, they must match.
• Default rate limit: 120 requests / minute.

curl https://api.mercel.app/v1/stores \
  -H "Authorization: Bearer mercel_pat_test_…"

There is no separate "login" call — send the credential in Authorization on every request.