Guide

Serial Activation Quickstart

Implement serial activation for custom JUCE/C++ clients, including claim, email verification, claim-status resume, final activation, cache, and unlock behavior.

Start with getting started Explore API docs

SoundSync

Prerequisites

Complete these before writing activation code.

Prerequisite	Exact requirement
Product configured	Product ID and activation mode exist in SoundSync.
Product credential created	You have App ID, plugin key, plugin secret, environment, and API base URL.
Test Connection passed	POST /api/plugin-connections/verify succeeds for productId, appId, pluginKey, and pluginSecret.
Test serial available	Use a serial/license key assigned to the product and environment under test.
Machine ID strategy selected	Use a stable per-machine instance_id/machine_id. Do not regenerate on each launch.
Secure persistence selected	Choose encrypted per-product, per-environment, per-machine storage before first activation.

SoundSync

State machine

Unlock only after the final activation response.

Serial flow

1. POST /api/license/v1/claim with license_key, instance_id, email.
2. Keep claim_id and pending state locally.
3. Customer verifies by email.
4. GET /api/license/v1/claim-status with license_key, instance_id, claim_id.
5. When status is verified, read claim_activation_token.
6. POST /api/license/v1/activate with license_key, instance_id, claim_activation_token.
7. Store validation_token, activationId, productId, status, grace fields, and support fields.
8. Unlock audio/access only after final activation succeeds.

SoundSync

Request sequence

These calls work together.

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.

SoundSync

Important answers

These are the behaviors custom clients most often get wrong.

Question	Answer
Does /claim activate the machine?	No. It creates/restores a pending claim and may send verification email.
Does email verification activate the machine?	No. It verifies the claim so the plugin can restore claim status.
Does /claim-status activate the machine?	No. A verified claim-status returns claim_activation_token.
What is passed to /activate?	license_key, instance_id, claim_activation_token, and optionally claim_id plus version/product context.
What survives restart?	Pending claim fields such as license_key, instance_id, claim_id, email, productId, environment, and started-at timestamp; do not store customer password.
How often may polling run?	HISE runtime observes 2-second polling up to 120 attempts. Custom clients should not poll faster than that.
What if the claim expires?	Claim verification tokens are 48-hour email tokens; claim activation material is short-lived. Restart claim if eligible.