Skip to content
SoundSyncAudio software platform

Guide

Validate on Startup

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

SoundSync

Startup sequence

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

  1. Read encrypted activation record

    Load per-product, per-environment, per-machine cache from secure storage.

  2. Validate schema

    Require status, productId, instance_id, and enough identity for validation such as token, activationId, licenseReference, or license_key context.

  3. Confirm context

    Check product, App ID, environment, and machine identity match the running build.

  4. 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.

  5. Send /validate

    Use product credential headers and canonical request fields.

  6. Interpret result

    Active updates cache and may rotate token. Explicit denied states lock immediately. Transport failures may use grace only if allowed.

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

  8. 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
  • content_protocol_version: 1 | 2. Use 2 with the matching maintained native package.
  • content_releases: array
  • previous_content_authorization: object
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. In bounded-grace mode, JUCE requires an authorized signed offline_lease. Protocol 2 permanent-device ownership instead requires the matching SDK to verify explicit signed product_authorization and any required content_authorization; the absence of an offline_lease alone is not a denial in that mode. Protocol 2 adds independently verified product/content authorizations. A pending status or catalog response is not playback permission. Product ownership spans releases; content software compatibility, account/device binding, epochs, signed deadlines and explicit denials remain enforced. permanent_device ownership has no recurring offline deadline only when an authorized signed product/content grant explicitly allows it; ordinary grace and subscription/trial permission remain bounded.
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"
    },
    "content_protocol_version": {
      "type": "integer",
      "enum": [
        1,
        2
      ],
      "description": "Use 2 with the matching maintained native package."
    },
    "content_releases": {
      "type": "array",
      "maxItems": 64,
      "items": {
        "type": "object",
        "properties": {
          "contentId": {
            "type": "string",
            "format": "uuid"
          },
          "releaseId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": true,
        "required": [
          "contentId",
          "releaseId"
        ]
      }
    },
    "previous_content_authorization": {
      "type": "object",
      "properties": {
        "alg": {
          "const": "RS256"
        },
        "kid": {
          "type": "string"
        },
        "payload": {
          "type": "string"
        },
        "signature": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "required": [
        "alg",
        "kid",
        "payload",
        "signature"
      ]
    }
  },
  "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."
    },
    "product_authorization": {
      "type": "object",
      "properties": {
        "alg": {
          "const": "RS256"
        },
        "kid": {
          "type": "string"
        },
        "payload": {
          "type": "string"
        },
        "signature": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "required": [
        "alg",
        "kid",
        "payload",
        "signature"
      ]
    },
    "content_authorization": {
      "type": "object",
      "properties": {
        "alg": {
          "const": "RS256"
        },
        "kid": {
          "type": "string"
        },
        "payload": {
          "type": "string"
        },
        "signature": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "required": [
        "alg",
        "kid",
        "payload",
        "signature"
      ]
    },
    "unavailable_content": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contentId": {
            "type": "string",
            "format": "uuid"
          },
          "releaseId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": true
      }
    },
    "other_major_authorizations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "host_version": {
            "type": "string"
          },
          "product_authorization": {
            "type": "object",
            "properties": {
              "alg": {
                "const": "RS256"
              },
              "kid": {
                "type": "string"
              },
              "payload": {
                "type": "string"
              },
              "signature": {
                "type": "string"
              }
            },
            "additionalProperties": true,
            "required": [
              "alg",
              "kid",
              "payload",
              "signature"
            ]
          },
          "content_authorization": {
            "type": "object",
            "properties": {
              "alg": {
                "const": "RS256"
              },
              "kid": {
                "type": "string"
              },
              "payload": {
                "type": "string"
              },
              "signature": {
                "type": "string"
              }
            },
            "additionalProperties": true,
            "required": [
              "alg",
              "kid",
              "payload",
              "signature"
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "protected_activation_id": {
      "type": "string"
    },
    "protected_authorization_status": {
      "type": "string",
      "enum": [
        "ready",
        "pending"
      ]
    }
  },
  "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.

ResultAccess behaviorLocal state action
Activated/validUnlock or keep unlocked.Store rotated token, timestamps, grace fields, subscription/license fields.
device_not_activatedLock.Clear invalid activation state.
device_deactivatedLock immediately.Delete activation cache.
subscription_payment_requiredLock immediately.Keep diagnostic/support info only.
Temporary network failureUse 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 responseDoes 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.9.3 supports signed offline access. In the bounded grace mode, successful online activation or validation applies the period selected in product Access settings, up to 90 days and capped by any earlier entitlement or subscription deadline. Zero, disabled, missing or expired grace requires online authorization in that mode. An explicitly authorized permanent-device purchase is different: its signed product/content grant can have no recurring offline deadline. Never infer permanent access from a cached date, a catalog response or an unsigned success flag. Confirmed denial and local deactivation lock access.

Bounded grace and explicit permanent ownership

Offline grace is not deactivation. A disconnected permanent-device grant cannot learn about a later server revocation instantly; reconnection applies the new decision. Local deactivation still locks immediately and retains the pending server-release proof. HISE has its own package contract and runtime-verification boundary; JUCE protected-bank behavior must not be assumed for HISE.

SoundSync

Match the integration to the policy

Ownership modes

Permanent grants, recurring rights and compatibility.

Package upgrade

Integrate, rebuild and release the matching package.