These docs match the active app-store routes, app-engine scope planning, auth-core token contracts, and webhook-service HMAC dispatcher.
Live contract
Authorization code
A merchant authorizes a published app through `/v1/app-store/apps/:id/oauth/authorize`. The gateway verifies store ownership, requested scopes, redirect URI, and PKCE S256 challenge before upserting an active installation.
Grant type is `authorization_code`.
Authorization codes are short lived and expire after 15 minutes.
The app must keep the original `code_verifier`; token exchange rejects missing or mismatched PKCE proof.
The response includes `redirect_to`, `code`, `state`, granted scopes, app id, installation id, and store id.
Live contract
Access token exchange
`POST /v1/app-store/oauth/token` exchanges the authorization code for a scoped app access token after checking client id, redirect URI, PKCE verifier, active installation, and one-time code redemption. The same endpoint supports `grant_type=refresh_token` and rotates the stored refresh-token hash.
Authorization-code and refresh-token responses include `access_token`, `refresh_token`, `token_type`, `expires_at`, `refresh_expires_at`, `scope`, and `scopes`.
Auth-core signs app access tokens as JWTs with normalized scopes.
The installation config stores token hashes, not raw returned access or refresh tokens.
Live contract
Embedded token exchange
`POST /v1/app-store/oauth/token-exchange` exchanges an authenticated merchant session for an embedded app token tied to an installation and store.
Requires protected merchant auth middleware.
Validates active installation and store ownership.
Used by embedded app surfaces and the app bridge fetch contract.
Webhook verification
HMAC over timestamp and raw body
The dispatcher sends `X-LetBuyy-Timestamp`, `X-LetBuyy-Hmac-SHA256`, event id, event type, request id, and trace id.
App lifecycle webhooks are sent by `services/webhook-service` and signed with the `X-LetBuyy-Hmac-SHA256` header.
Signature payload is `X-LetBuyy-Timestamp + '.' + rawBody`.
Header value is versioned as `v1=<hex-hmac>`.
The legacy `X-LetBuyy-Signature` header is also sent for compatibility.
Live contract
Delivery headers
Webhook deliveries include event, request, trace, and timestamp metadata so receivers can verify, deduplicate, and correlate processing.
Headers include event id, event type, request id, trace id, timestamp, and HMAC signature.
Webhook targets must be HTTPS in staging and production.
The service records response status, a response preview, and request errors.
Live contract
Compliance topics
App-engine always includes mandatory compliance topics when planning app webhook subscriptions, and the app-store gateway emits those topics from compliance producer routes.