API Reference

Downloads and Secure Delivery API

Contract-backed secure delivery documentation for entitlement-gated file streaming and legacy download compatibility routes.

Start with getting started Explore API docs

SoundSync

Verified delivery endpoint

This is the canonical current route for entitlement-gated delivery.

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.

SoundSync

Download example

The token is a temporary customer/library token. Do not place product plugin credentials in browser download links.

curl

curl -L "$SOUNDSYNC_API_BASE/api/delivery/entitlements/1042/files/0" \
  -H "Authorization: Bearer $CUSTOMER_LIBRARY_TOKEN" \
  -o NebulaKeysInstaller.zip

SoundSync

Delivery behavior

Documented exactly from the route/controller.

Case	Response	Client behavior
Missing token	401 JSON { message: Missing token }	Prompt customer to sign in or refresh library token.
Invalid entitlement id or file index	400 JSON error	Treat as integration or stale-link bug.
Entitlement not found	404 JSON error	Refresh customer library and do not retry file URL blindly.
Entitlement inactive	403 JSON error	Block download; explain refund, expiration, or revoked access where known.
File index missing	404 JSON error	Refresh library product file list/version.
Unmanaged external file	409 JSON EXTERNAL_FILE_NOT_IMPORTED	Prompt the developer to re-import the file with Upload by Link.
Successful managed R2 file	302 redirect to short-lived signed R2 URL	Let the browser follow the redirect and save the file; do not expose backing object keys in library payloads.

Signed URL note

The verified canonical entitlement route does not expose raw storage URLs in library payloads. It generates signed R2 delivery only after a customer starts an authorized download, with short expiry and no-store cache headers.