Authentication

The Solid Commerce API supports two authentication modes:

| Mode | Use it for | Token type | |------|------------|------------| | OAuth 2 authorization code | Multi-tenant ISV apps acting on behalf of merchants | Short-lived access token + refresh token | | API key | First-party scripts, CLI, MCP server, single-tenant automations | Long-lived bearer token, scoped to one company |

All requests must include an Authorization: Bearer <token> header.

OAuth 2 authorization code

1. Send the merchant to https://auth.solidcommerce.com/oauth/authorize with response_type=code, client_id, redirect_uri, scope, state.
2. Exchange the returned code at /oauth/token for an access + refresh token.
3. Use the access token; refresh before expiry.

API keys

Create keys in the developer dashboard. Each key:

• Belongs to one company.
• Carries an explicit list of scopes (e.g. catalog:products:read).
• Logs a last_used_at timestamp on every call.
• Can be rotated or revoked at any time.

Rotate keys quarterly at minimum. Keep them out of source control.

Scope syntax

Scopes follow <segment>:<resource>:<action>. For example:

• catalog:products:read
• orders:orders:write
• webhooks:subscriptions:write

A 401 response with WWW-Authenticate: Bearer error="insufficient_scope" means the token is valid but missing the required scope.