Downloads and Secure Delivery API

Authorizes an active customer entitlement and redirects to short-lived signed R2 delivery.

Auth

Customer library/download token

Scope

Entitlement, customer identity, product, source/sourceId, expansion rule, and file-index scoped.

Request fields

• query token: string
• query download_token: string
• query libraryToken: string

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. fileIndex is zero-based. Token ownership, active entitlement, expansion rules and file existence are checked before redirect. Do not persist the storage URL as a permanent download. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. Shared library tokens follow their own token/ownership checks.

[
  {
    "name": "token",
    "in": "query",
    "schema": {
      "type": "string"
    },
    "required": false,
    "description": ""
  },
  {
    "name": "download_token",
    "in": "query",
    "schema": {
      "type": "string"
    },
    "required": false,
    "description": ""
  },
  {
    "name": "libraryToken",
    "in": "query",
    "schema": {
      "type": "string"
    },
    "required": false,
    "description": ""
  }
]

{
  "Location": {
    "schema": {
      "type": "string",
      "format": "uri"
    },
    "description": "Short-lived authorized private download URL."
  }
}

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