Guide

Validate on Startup

Startup sequence for reading cached activation state, validating online, updating the cache, and deciding audio/access behavior.

Start with getting started Explore API docs

SoundSync

Startup sequence

Treat the local record as untrusted input until it passes schema and context checks.

Read encrypted activation record
Load per-product, per-environment, per-machine cache from secure storage.
Validate schema
Require status, productId, instance_id, and enough identity for validation such as token, activationId, licenseReference, or license_key context.
Confirm context
Check product, App ID, environment, and machine identity match the running build.
Decide access by integration
JUCE may start from a verified unexpired offlineLease for this product, activation and device; otherwise successful online authorization is required. Its processor-owned worker revalidates asynchronously, including with the editor closed. Other clients follow their own documented contract.
Send /validate
Use product credential headers and canonical request fields.
Interpret result
Active updates cache and may rotate token. Explicit denied states lock immediately. Transport failures may use grace only if allowed.
Update atomically
Preserve the returned signed offline_lease with the matching identity and deadline, along with rotated token and other state. Use the maintained JUCE storage rather than inventing a native cache format.
Schedule next validation
Use product policy; do not reset grace locally by restarting.

SoundSync

Validation endpoint

The validation token may rotate. Store the newest returned token.

POST /api/license/v1/validate

Validate cached activation state on startup or during periodic revalidation.

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: Product, app, credential, environment, and machine scoped.
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
device_credential: string. Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio.
license_kind: serial | email_entitlement
device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.
claim_id: string
claim_activation_token: string
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.
Notes: Generated native clients request device_credential_supported:true and retain the returned device_credential, plugin_session_id and newest validation_token privately. Device proof can renew after a short-lived token/session expires, but never bypasses revoked access, product/device binding or entitlement checks. device_credential_status:pending is incomplete enrollment, not an offline grant. Only an authorized signed offline_lease can support JUCE offline access.

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"
    },
    "device_credential": {
      "type": "string",
      "description": "Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio."
    },
    "license_kind": {
      "type": "string",
      "enum": [
        "serial",
        "email_entitlement"
      ]
    },
    "device_credential_supported": {
      "type": "boolean",
      "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias."
    },
    "claim_id": {
      "type": "string"
    },
    "claim_activation_token": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "instance_id"
      ]
    },
    {
      "required": [
        "machine_id"
      ]
    }
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "activationId": {
      "type": "integer",
      "minimum": 1
    },
    "validation_token": {
      "type": "string"
    },
    "entitlement_id": {
      "type": "integer",
      "minimum": 1
    },
    "customer": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "device_credential": {
      "type": "string",
      "description": "Private product/device-bound renewal proof. Returned when device_credential_supported is true and enrollment succeeds. Protect it in native secure storage; it is not a portal/library token or an offline grant."
    },
    "device_credential_status": {
      "type": "string",
      "enum": [
        "ready",
        "pending"
      ],
      "description": "pending means renewal enrollment is incomplete, even when activation was otherwise authorized. Follow the maintained client retry and access decision; do not manufacture offline authorization."
    },
    "plugin_session_id": {
      "type": "string",
      "description": "Private short-lived plugin license session. Distinct from durable device_credential and customer library tokens."
    },
    "plugin_session_expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "Expiry of plugin_session_id, not the offline grace deadline."
    },
    "max_activations": {
      "type": "integer",
      "minimum": 0
    },
    "remaining": {
      "type": "integer",
      "minimum": 0
    },
    "grace_expires_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "offline_grace_days": {
      "type": "integer",
      "minimum": 0
    },
    "offline_grace": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "days": {
          "type": "integer",
          "minimum": 0
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": true
    },
    "offline_lease": {
      "type": "string",
      "description": "Optional signed JSON envelope issued only by successful authorized activation/validation with a positive grace period and configured signer. Contains alg, kid, base64 payload and signature. Verify with trusted package public keys; decoding alone is not authorization. Never log customer grants."
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 500, 503.

SoundSync

Validation request

The license key does not have to be resent when a valid token/activation identity is available, but instance_id/machine_id is required.

cURL

curl -sS -X POST "$SOUNDSYNC_API_BASE/api/license/v1/validate" \
  -H "Content-Type: application/json" \
  -H "x-ss-app-id: ss_prod_demoapp123" \
  -H "x-ss-plugin-key: ss_pk_demokey123" \
  -H "x-ss-plugin-secret: ss_ps_demosecret123" \
  -d '{
    "instance_id": "machine-demo-001",
    "token": "validation-token-from-activation",
    "product_id": 23794
  }'

SoundSync

Client decision table

Never permit grace for explicit platform denials.

Result	Access behavior	Local state action
Activated/valid	Unlock or keep unlocked.	Store rotated token, timestamps, grace fields, subscription/license fields.
device_not_activated	Lock.	Clear invalid activation state.
device_deactivated	Lock immediately.	Delete activation cache.
subscription_payment_required	Lock immediately.	Keep diagnostic/support info only.
Temporary network failure	Use only the integration-authorized grace. JUCE requires a verified, unexpired offlineLease bound to this product, activation and device, not just a future graceExpiresAt.	Preserve the signed deadline; retry with the package backoff. Never reset grace at the first failure.
Non-JSON or malformed response	Does not establish new authorization. Any continued access must independently satisfy the package grace verifier and existing deadline.	Record sanitized diagnostics. Do not invent a grant, extend a deadline, or replace valid cache with malformed data.

Package-specific access policy

JUCE 0.7.3 supports signed offline access for the grace period selected in product Access settings, through 90 days. A prior successful activation or validation and the matching package verification keys are required. Startup uses a verified unexpired grant or online authorization. Zero, disabled, missing or expired grace requires online authorization; confirmed denial or deactivation locks access. Regenerate and rebuild older plugins to use this release.

Startup sequence

Read encrypted activation record

Validate schema

Confirm context

Decide access by integration

Send /validate

Interpret result

Update atomically

Schedule next validation

Validation endpoint

Request (application/json)

HTTP 200 response (application/json)

Validation request

Client decision table

Package-specific access policy