API Reference
Entitlements API
Verified entitlement concepts and the current public delivery endpoint that authorizes files from active customer entitlements.
SoundSync
Verified endpoints
Only endpoint-backed behavior is documented here.
GET
/api/delivery/entitlements/:entitlementId/files/:fileIndex
Authorizes an active customer entitlement and redirects to short-lived signed R2 delivery.
- Auth
- Customer library/download token. Accepted transports are Authorization: Bearer <token>, token, download_token, or libraryToken.
- Scope
- Entitlement, customer identity, product, source/sourceId, expansion rule, and file-index scoped.
- Request fields
- entitlementId numeric path parameter
- fileIndex zero-based numeric path parameter
- Bearer library/download token or token/download_token/libraryToken query alias
- Returns
- 302 redirect to a short-lived signed R2 download URL, or JSON error for missing token, invalid entitlement/file index, inactive entitlement, expansion block, missing file, upstream failure, or delivery failure.
- Side effects
- Logs delivery and updates legacy serial download count when the entitlement metadata includes a serialId.
- Notes
- This endpoint keeps authorization and download accounting in SoundSync while R2 serves the file bytes directly.
POST
/api/products/:id/delivery-files
Attach product delivery-file metadata from the developer product setup flow.
- Auth
- Developer dashboard/user JWT.
- Scope
- Developer-owned product setup.
- Request fields
- Developer JWT
- product id path parameter
- delivery file metadata body
- Returns
- Product setup response controlled by product setup service.
- Side effects
- May update delivery-file configuration for the product. Not safe for read-only screenshot capture.
SoundSync
Lifecycle sources
The implementation creates or validates entitlements from these sources.
| Source | Creates or updates entitlement? | Public API surface | Notes |
|---|---|---|---|
| Purchase checkout | Yes | /api/checkout/product and Stripe webhook flows | Checkout/webhook implementation creates order and subscription-linked access; docs here do not expose internal webhook handlers as public customer APIs. |
| Serial activation/redeem | Yes | Licensing and redeem flows | Legacy serial download paths bridge to entitlements when possible. |
| Subscription checkout | Yes | Subscription checkout and Stripe subscription webhooks | Beta-gated; states are documented in Subscriptions API. |
| Partner external order | Yes | /api/partner/v1/orders | Partner API order fulfillment can enqueue order.fulfilled webhooks and create fulfillment material. |
| Manual grant | Implementation-dependent | Developer dashboard, not a verified public endpoint in this pass | Do not publish a manual-grant API until a route-level contract is verified. |
Revocation and refunds
Refund, dispute, subscription expiration, serial revocation, and partner revoke flows can make access inactive. Clients must not assume a stored entitlement remains downloadable; always call the delivery endpoint with a current library token.