OAuth architecture and token lifecycle

This implementation includes the merchant login, store selection and explicit consent journey. Marketplace remains disabled in the current release policy while full event and environment acceptance is completed. A disabled environment returns no authorization service; do not treat this reference as a launch announcement.

Start authorization

Navigate the browser to GET /api/oauth/authorize with all seven query parameters below. The endpoint opens the localized platform consent page. Applications may use /ar/oauth/authorize or /en/oauth/authorize to select the language explicitly.

Unknown or repeated parameters are rejected. Redirects require HTTPS, except registered loopback HTTP callbacks for local development. Generate a fresh verifier and state for each journey; keep them server-side. The platform never redirects to an unvalidated callback.

Merchant review

The merchant signs in and returns to the platform consent page. It displays the reviewed app name, version and permission descriptions. Only active stores where the merchant is an owner or administrator can be selected. Viewing the page grants nothing. The merchant explicitly approves or declines within five minutes.

Approval is valid only while the reviewed publication, membership, store and existing installation still match the review. Changes require a fresh journey. Reauthorizing a subset of an existing installation's grants does not silently remove its other grants. The resulting token is limited to the requested subset and selected store.

The page submits its one-use review through a same-origin authenticated platform action at POST /api/oauth/authorize. External applications must start with GET; posting installation IDs or arbitrary scopes directly is not the consent contract. JavaScript is required for the reviewed page's submission and callback navigation.

Callback and token exchange

Approval returns code and the original state to the exact registered callback. Decline returns error=access_denied and state, without a code. Validate state before acting. If the platform cannot confirm the outcome, restart the journey rather than repeatedly submitting an old approval.

Exchange at POST /api/oauth/token with grant_type=authorization_code, client_id, code, the same redirect_uri, and the original code_verifier. Form-encoded and JSON bodies are supported. There is no client secret. The endpoint also accepts the refresh_token grant.

Token properties

• Access tokens last 15 minutes; rotating refresh tokens last 30 days.
• Credentials bind to the active developer, app, exact installed reviewed version and installation authorization generation.
• Reviewed scopes also bind to versioned operational contracts. A broader contract requires fresh review and merchant consent.
• Only token hashes are stored at rest.
• Codes are consumed once. Refresh reuse revokes the token family and installation access tokens.

Secure storage and revocation

Keep tokens and verifiers in encrypted server-side storage. Never place them in browser storage, URLs, analytics, screenshots, support tickets or logs. Redact authorization headers and token responses. Consent responses forbid caching, referrers and framing.

Uninstall clears grants, disables subscriptions and revokes derived authority. Suspension or invalid reviewed-version authority also fails closed. A reinstall creates fresh authority, so old codes and tokens cannot revive. Delivery admission checks revocation after DNS resolution; a request already admitted to the network cannot be recalled. Receivers must deduplicate stable event IDs and honor revoked merchant access.