Marketplace & OAuth
Connect external apps to an Openfront store with OAuth apps, API keys, customer tokens and webhooks.
External systems, such as an order management system or a marketplace, can reach store data without a dashboard session. The current source has four credential types and an outgoing webhook system.
Credentials
| Credential | Prefix | Issued by | Acts as |
|---|---|---|---|
| API key | of_ | /dashboard/platform/api-keys | The key's owner, limited to the key's scopes, optional IP allowlist and expiry |
| OAuth app token | — | /api/oauth/authorize and /api/oauth/token | The approving operator, limited to the granted scopes |
| Customer token | ctok_ | regenerateCustomerToken on the storefront | A business customer (see B2B accounts) |
| MCP token | mcp_at_ | /oauth/* routes | The approving user, for MCP clients (see AI assistant) |
All are sent as Authorization: Bearer <token>. API-key and OAuth scopes map to permissions in features/keystone/oauth/scopes.ts. Scopes come in read and write pairs for products, orders, customers, fulfillments, checkouts, discounts, gift cards, returns, sales channels, payments, webhooks and apps.
OAuth app flow
Register the app
An OAuthApp record holds the name, clientId, clientSecret, redirect URIs, allowed scopes, status, and optional install, uninstall, webhook, privacy and support URLs. Creating one requires canManageApps. /dashboard/platform/apps lists apps and can suspend, activate, edit redirect URIs or delete them.
Authorize
The app sends the operator to /api/oauth/authorize?client_id=...&response_type=code&redirect_uri=...&scope=.... The operator must be signed in with dashboard access. The redirect URI must be registered, and every scope must be both known and allowed for the app. PKCE (plain or S256) is supported. The /dashboard/platform/order-management-system and /dashboard/platform/apps pages show an install dialog when opened with ?install=true and the same parameters.
Exchange the code
The app posts to /api/oauth/token with grant_type=authorization_code (or refresh_token), its client credentials and, if used, the PKCE verifier.
Webhooks
registerWebhookEndpoint(registrationKey, url, events, secret, requiredScope) creates or updates a subscription for the caller. It needs canManageWebhooks, except that a customer token may subscribe only to fulfillment.created. URLs must be HTTPS (plain HTTP is allowed for localhost outside production) and cannot contain credentials.
Deliveries are signed with HMAC-SHA256 using the endpoint secret, in the X-OpenFront-Webhook-Signature: sha256=... header. Events include order.canceled, order.archived, fulfillment.created and payment.captured, among others raised by the webhook plugin. Failed deliveries are retried only when someone with canManageWebhooks calls retryWebhookDeliveries.
- Scopes only add permissions. They do not narrow a token below its owner's role; test each operation you expose with the exact key.
- There is no scheduled retry for webhooks.
- The
MARKETPLACE_TOKEN_SECRETentry in.env.exampleis not read by the current code.