Guide
Licensing Overview
How SoundSync plugin licensing moves from product credentials to activation, local state, validation, offline grace, and deactivation.
SoundSync
Core plugin endpoints
These are the Phase 2 fully documented plugin-facing endpoints.
/api/plugin-connections/verify
Verify product, App ID, plugin key, and plugin secret belong together before 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
- appId
- pluginKey
- pluginSecret
- pluginVersion optional
- environment 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.
/api/license/v1/claim
Start a serial claim when customer identity or email verification is required.
- Auth
- Product plugin credential. Licensing endpoints require x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret headers, or verified body/query aliases.
- Scope
- Product, app, credential, environment, and machine scoped.
- Request fields
- license_key
- instance_id
- 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.
/api/license/v1/claim-status
Restore a pending serial claim and receive claim activation material after email verification.
- Auth
- Product plugin credential. Licensing endpoints require x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret headers, or verified body/query aliases.
- 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.
/api/license/v1/activate
Activate the current machine after direct serial/customer proof or a verified serial claim.
- Auth
- Product plugin credential. Licensing endpoints require x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret headers, or verified body/query aliases.
- 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.
/api/license/v1/customer-login/activate
Activate by customer account identity when the product supports account/login activation.
- Auth
- Product plugin credential. Licensing endpoints require x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret headers, or verified body/query aliases.
- Scope
- Product, app, credential, environment, and machine scoped.
- Request fields
- 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.
/api/license/v1/validate
Validate cached activation state on startup or during periodic revalidation.
- Auth
- Product plugin credential. Licensing endpoints require x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret headers, or verified body/query aliases.
- 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.
/api/license/v1/deactivate
Deactivate this machine and release local access.
- Auth
- Product plugin credential. Licensing endpoints require x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret headers, or verified body/query aliases.
- 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
Access lifecycle
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.