Guide

Licensing Overview

How SoundSync plugin licensing moves from product credentials to activation, local state, validation, offline grace, and deactivation.

SoundSync

Core plugin endpoints

Product connection, claims, activation, validation, and deactivation have distinct authentication and access effects.

POST /api/plugin-connections/verify

Verify the standard product credential tuple or supported native public-client app/product identity before customer activation testing.

Auth: JSON body credential check. Headers are not used for this endpoint.
Scope: Product, app, credential, environment, and machine scoped.
Request fields: productId and appId
pluginKey and pluginSecret for standard custom HTTP/HISEScript credential verification
publicClient: hise-native or juce-native for the generated native public-client path
pluginVersion, environment, and metadata optional
Returns: ok/connected, productId, credentialId, pluginVersion, environment, lastSeenAt.
Side effects: Updates credential last-used state, upserts plugin connection status, and records a plugin connection event.
Notes: This endpoint reads its JSON body rather than substituting licensing headers. The native public-client path does not require a distributed pluginSecret. Connectivity/product identification is not customer entitlement or audio unlock.

POST /api/license/v1/claim

Start a serial claim when customer identity or email verification is required.

Auth: Standard custom HTTP/HISEScript product credential path: x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret. Generated native clients use their supported public-client identity and customer/machine proof path; see /docs/authentication.
Scope: Product, app, credential, environment, and machine scoped.
Request fields: license_key
instance_id
email
product_id optional when not inferred
Returns: pending_email_verification with claim_id/claimId and emailSent when verification is required.
Side effects: Creates or restores a pending serial claim and can send the verification email.

GET/POST /api/license/v1/claim-status

Restore a pending serial claim and receive claim activation material after email verification.

Auth: Standard custom HTTP/HISEScript product credential path: x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret. Generated native clients use their supported public-client identity and customer/machine proof path; see /docs/authentication.
Scope: Product, app, credential, environment, and machine scoped.
Request fields: license_key
instance_id
claim_id optional
Returns: pending_email_verification or verified with claim_activation_token/claimActivationToken.
Side effects: Does not activate the machine. The client must call /activate after verified status.

POST /api/license/v1/activate

Activate the current machine after direct serial/customer proof or a verified serial claim.

Auth: Standard custom HTTP/HISEScript product credential path: x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret. Generated native clients use their supported public-client identity and customer/machine proof path; see /docs/authentication.
Scope: Product, app, credential, environment, and machine scoped.
Request fields: license_key or serial
instance_id or machine_id
claim_activation_token when using verified claim
claim_id optional
plugin_version optional
Returns: status activated, activationId, validation_token, entitlement_id, customer, max_activations, remaining, productId, grace_expires_at, offline_grace_days.
Side effects: Creates or reactivates a machine activation, ensures entitlement state, marks serial redeemed/billing eligible where applicable, records events, and issues a validation token.

POST /api/license/v1/customer-login/activate

Activate by customer account identity when the product supports account/login activation.

Auth: Standard custom HTTP/HISEScript product credential path: x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret. Generated native clients use their supported public-client identity and customer/machine proof path; see /docs/authentication.
Scope: Product, app, credential, environment, and machine scoped.
Request fields: email
password or customer_token
instance_id or machine_id
product_id/app context when required
plugin_version optional
Returns: activation result with validation token, entitlement/customer details, device limit and subscription state where applicable.
Notes: Never cache the customer password. Store only returned activation state and validation token.

POST /api/license/v1/validate

Validate cached activation state on startup or during periodic revalidation.

Auth: Standard custom HTTP/HISEScript product credential path: x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret. Generated native clients use their supported public-client identity and customer/machine proof path; see /docs/authentication.
Scope: Product, app, credential, environment, and machine scoped.
Request fields: instance_id or machine_id
validation_token/token or activationId/licenseReference/license key context
product_id optional
Returns: active/denied state, rotated validation token, last validation timestamps, offline grace fields, subscription/license state.
Side effects: Refreshes validation state and token when allowed. Explicit denials force lock and must not use offline grace.

POST /api/license/v1/deactivate

Deactivate this machine and release local access.

Auth: Standard custom HTTP/HISEScript product credential path: x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret. Generated native clients use their supported public-client identity and customer/machine proof path; see /docs/authentication.
Scope: Product, app, credential, environment, and machine scoped.
Request fields: license_key or customer/email entitlement context
instance_id or machine_id
Returns: status deactivated, code DEVICE_DEACTIVATED, remaining_activations.
Side effects: Sets deactivated_at on the activation, records an event, and should cause the client to delete local activation state.

SoundSync

Keep audio/access decisions outside the network layer.

No local activation
Show activation UI. Do not unlock from missing or corrupt cache.
Claim or login
Collect serial/email or customer login according to product activation mode.
Final activation
Unlock only after /activate or /customer-login/activate returns an activated/allowed state.
Startup validation
Read encrypted cache and call /validate asynchronously.
Temporary failure
Use offline grace only if cache is valid and the failure is transport-level.
Hard denial
Lock immediately on explicit platform denial such as device_deactivated or subscription_payment_required.
Deactivation
Call /deactivate and delete local activation state.