Guide

Licensing API

Endpoint reference for claim, claim-status, activate, customer-login activate, validate, and deactivate.

POST /activateGET /validatePOST /deactivate

Product credentials
Activation request
Entitlement check
Device registration
Periodic validation
Deactivation when needed

SoundSync

Documented licensing endpoints

Use v1 endpoints for new custom integrations.

POST /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
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: 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.

POST /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.

POST /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: 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: 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.

POST /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.