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 workspace and issued from the dashboard under Developers → API keys. They can read and write the bound workspace'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 workspace 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 workspace. 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.
• Workspace binding comes from the URL path on workspace-scoped routes (/v1/workspaces/{workspaceId}/...); the user must be a member of workspaceId or the request returns 403.
• On routes that don't carry a workspace id in the path (e.g. /v1/products), send the Mercel-Workspace-Id: wsp_… header to scope the request. If both the path and the header name a workspace, they must match.
• Default rate limit: 120 requests / minute.

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

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