API Reference
Customer Library API
Verified customer-library token, listing, webview-library, expansion, review, and claim boundaries.
SoundSync
Verified library endpoints
These endpoints are route-backed and scoped by customer/library token where noted.
/api/library
Return customer portal/library payload for a library token.
- Auth
- Customer library/download token
- Scope
- Customer identity plus optional storefront/developer scope.
- Request fields
- query token: string
- query download_token: string
- query libraryToken: string
- Returns
- Products, subscriptions, licenses/serials, orders, marketing preferences, account profile, support, and download_token.
- Side effects
- None for GET endpoints unless noted.
- Notes
- 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.
Request, response and error reference
Query and header parameters
[
{
"name": "token",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "download_token",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "libraryToken",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
]HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"licenses": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"orders": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"prefs": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"profile": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"support": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"download_token": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 401, 503.
Operation errors: SESSION_VERIFICATION_UNAVAILABLE, LIBRARY_SESSION_REVOKED.
/api/license/v1/library-token
Issue or return a customer library token for plugin/webview customer-library access.
- Auth
- x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)
- Scope
- Customer/library session scope.
- Request fields
- query instance_id: string
- query validation_token: string
- query plugin_session_id: string
- Returns
- Library token response used by HISE storefront package and webview-library flows.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
Query and header parameters
[
{
"name": "instance_id",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "validation_token",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "plugin_session_id",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
]HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"token": {
"type": "string"
},
"library_token": {
"type": "string"
},
"expiresIn": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}Documented failures: 400, 403, 500.
/api/license/v1/library-token
Issue or return a customer library token for plugin/webview customer-library access.
- Auth
- x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)
- Scope
- Customer/library session scope.
- Request fields
- instance_id: string
- machine_id: string
- product_id: integer
- plugin_version: string
- version: string
- license_key: string
- serial: string
- email: string
- validation_token: string
- token: string
- activationId: value
- licenseReference: string
- plugin_session_id: string
- key: string
- Returns
- Library token response used by HISE storefront package and webview-library flows.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"instance_id": {
"type": "string"
},
"machine_id": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"plugin_version": {
"type": "string"
},
"version": {
"type": "string"
},
"license_key": {
"type": "string"
},
"serial": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"validation_token": {
"type": "string"
},
"token": {
"type": "string"
},
"activationId": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"licenseReference": {
"type": "string"
},
"plugin_session_id": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"token": {
"type": "string"
},
"library_token": {
"type": "string"
},
"expiresIn": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}Documented failures: 400, 403, 500.
/api/license/v1/webview-library
Return webview customer-library payload for plugin-hosted library experiences.
- Auth
- x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)
- Scope
- Customer library and product/storefront scope.
- Request fields
- query instance_id: string
- query validation_token: string
- query plugin_session_id: string
- Returns
- Customer library payload suitable for in-plugin WebView use.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
Query and header parameters
[
{
"name": "instance_id",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "validation_token",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "plugin_session_id",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
]HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"status": {
"type": "string"
},
"libraryToken": {
"type": "string"
},
"library_token": {
"type": "string"
},
"download_token": {
"type": "string"
},
"expiresIn": {
"type": "integer",
"minimum": 0
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 403, 500.
/api/license/v1/webview-library
Return webview customer-library payload for plugin-hosted library experiences.
- Auth
- x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)
- Scope
- Customer library and product/storefront scope.
- Request fields
- instance_id: string
- machine_id: string
- product_id: integer
- plugin_version: string
- version: string
- license_key: string
- serial: string
- email: string
- validation_token: string
- token: string
- activationId: value
- licenseReference: string
- plugin_session_id: string
- key: string
- Returns
- Customer library payload suitable for in-plugin WebView use.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"instance_id": {
"type": "string"
},
"machine_id": {
"type": "string"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"plugin_version": {
"type": "string"
},
"version": {
"type": "string"
},
"license_key": {
"type": "string"
},
"serial": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"validation_token": {
"type": "string"
},
"token": {
"type": "string"
},
"activationId": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"licenseReference": {
"type": "string"
},
"plugin_session_id": {
"type": "string"
},
"key": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"status": {
"type": "string"
},
"libraryToken": {
"type": "string"
},
"library_token": {
"type": "string"
},
"download_token": {
"type": "string"
},
"expiresIn": {
"type": "integer",
"minimum": 0
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 403, 500.
/api/library/claim
Claim an external reseller/partner order item into the authenticated customer/developer account.
- Auth
- Account Bearer JWT
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Request fields
- claim: string
- claim_token: string
- Returns
- Claim result or LIBRARY_CLAIM_FAILED error.
- Side effects
- Claims an external reseller order item when the claim token is valid.
- Notes
- Requires an account JWT and a supported private claim token. claim is also accepted as a query alias. It does not create payment authority.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"claim": {
"type": "string"
},
"claim_token": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"claimed": {
"type": "boolean"
},
"redirect_to": {
"type": "string"
},
"customer_id": {
"type": "integer",
"minimum": 1
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
},
"order": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"external_order_id": {
"type": "string"
}
},
"additionalProperties": true
},
"license": {
"type": "object",
"properties": {
"serial": {
"type": [
"string",
"null"
]
},
"entitlement_id": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
SoundSync
Purchase to library flow
This is the verified conceptual flow; do not expose internal-only endpoints.
-
Purchase/order
Checkout or partner fulfillment records product access.
-
Entitlement
Entitlement state is the access source used by delivery.
-
Customer account/link
Customer identity service resolves user/customer IDs from the token.
-
Library item
GET /api/library returns products, serials/licenses, subscriptions, and support context.
-
Download
Download links point to entitlement-gated delivery routes.
-
Plugin activation
Licensing endpoints remain separate from library listing.
Public boundary
Customer website UI, embedded customer library, in-plugin WebView library, and developer API access are separate surfaces. Do not document internal customer tables or admin routes as public APIs.
SoundSync
Customer activation reset
/api/library/licenses/:kind/:licenseId/reset-activations
Reset the current customer's eligible device activations
- Auth
- Account Bearer JWT
- Scope
- License ownership, developer reset enablement, cooldown, and storefront scope are checked.
- Request fields
- query storefront: string
- expectedLastResetAt: string,null (required)
- Returns
- Updated reset result or an eligibility/conflict error; reload before another action.
- Notes
- kind is serial or entitlement. Account Bearer token only, not a shared library/download link. Send null before the first reset or the exact last value read. Enablement, cooldown, current active devices and stale-state conflicts are checked. 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.
Request, response and error reference
Query and header parameters
[
{
"name": "storefront",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]Request (application/json)
{
"type": "object",
"properties": {
"expectedLastResetAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"expectedLastResetAt"
],
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"reset": {
"type": "boolean"
},
"resetCount": {
"type": "integer"
},
"serialCount": {
"type": "integer"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503, 401.
Operation errors: SESSION_VERIFICATION_UNAVAILABLE, LIBRARY_SESSION_REVOKED.
Customer activation resets, when enabled
Developers can allow customer self-service resets for supported serial and entitlement licenses, with a configured cooldown. Only the signed-in owner of the license can request a reset. The confirmation clears the affected device activations and sessions together while preserving the license and product ownership.
A reset is not a refund, a new serial, or unlimited extra devices. Customers must reload the current state and wait for the next eligible reset when a cooldown applies.
Current access and previous records
The customer account separates current licenses and plans from Previous licenses and Previous subscriptions. Ended or inactive records stay available in expandable history; a plan with remaining eligible paid-through access is not hidden merely because cancellation is scheduled.
A signed-in marketplace customer who already owns a product can open their library and downloads from its product page. This is an account-specific lookup, not a public ownership list. License-reset cooldowns show the next eligible date; resetting activations does not create another license.
Account sessions must be verifiable
A signed account token is not enough on its own: customer account requests also check that the session is still allowed. If that check is unavailable, protected library, invoice, review, device-reset, download and customer-token activation requests stop before returning private data or performing the protected action.
503 SESSION_VERIFICATION_UNAVAILABLE means verification could not finish. Retry after service recovery; it does not mean that the purchase disappeared or the session was confirmed revoked. A confirmed revoked session returns 401 LIBRARY_SESSION_REVOKED and requires sign-in again. Do not grant access on either response.
Shared library/download tokens retain their separate token and ownership checks. Optional storefront personalization can fall back to anonymous browsing when customer identity cannot be established; that does not authorize a private download. This account-session check does not replace the signed JUCE offline-grant policy.
SoundSync