Skip to content
SoundSyncAudio software platform

Guide

Licensing API

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

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
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 (required)
  • email: string (required)
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.
Notes
Requires a serial/license_key, customer email and instance_id (machine_id is an alias). A pending response includes claim_id and emailSent:true; it does not activate the device. 503 VERIFICATION_EMAIL_FAILED with emailSent:false is not confirmed delivery or authorization: retry the claim deliberately after recovery. Owner mismatch/login-required errors do not transfer ownership. Keep the same serial and machine through claim-status and final activation. A compatibility CUSTOMER_ACCOUNT_EXISTS response directs account login/password recovery, not 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"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": [
    "license_key",
    "email"
  ],
  "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"
    },
    "claim_id": {
      "type": "string"
    },
    "claimId": {
      "type": "string"
    },
    "emailSent": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "nextAction": {
      "type": "string"
    },
    "passwordResetUrl": {
      "type": "string"
    },
    "claimRequired": {
      "type": "boolean"
    },
    "ownerVerificationRequired": {
      "type": "boolean"
    },
    "requiredFields": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "claim_activation_token": {
      "type": "string"
    },
    "claimActivationToken": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

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

Operation errors: IDENTITY_FIELDS_REQUIRED, INVALID_EMAIL, SERIAL_OWNER_EMAIL_MISMATCH, SERIAL_OWNER_LOGIN_REQUIRED, VERIFICATION_EMAIL_FAILED.

GET /api/license/v1/claim-status

Restore a pending serial claim and receive claim activation material after email verification.

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
  • query license_key: string (required)
  • query instance_id: string (required)
  • query claim_id: string
  • query format: value. Optional compact HISE transport on successful serial activation or claim-status; default is JSON.
Returns
pending_email_verification, verified with claim_activation_token/claimActivationToken, or identity_required. Inspect status/code and ok; HTTP 200 alone is not activation.
Side effects
Does not activate the machine. The client must call /activate after verified status.
Notes
HTTP 200 may mean pending_email_verification, verified or identity_required; inspect status/code and ok. Only verified returns claim_activation_token for a separate final POST /activate on the same product/serial/machine. 400 VERIFICATION_RESTART_REQUIRED means the link expired or was not sent: submit email and serial to /claim again instead of polling forever. A confirmed owner/access denial is not offline grace. Pending polling/finalization can retry transient outages without discarding the saved claim. GET is a compatibility transport; prefer POST to keep serial/proof out of URLs and logs. A query format=hise_text or hise_text selects compact SSCLAIM text for successful claim-status transport. Default JSON preserves the full response; an HTTP 200 identity/pending state is not activation.
Request, response and error reference

Query and header parameters

[
  {
    "name": "license_key",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "instance_id",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "claim_id",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "format",
    "in": "query",
    "required": false,
    "schema": {
      "const": "hise_text"
    },
    "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
  }
]

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "claim_id": {
      "type": "string"
    },
    "claimId": {
      "type": "string"
    },
    "emailSent": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "nextAction": {
      "type": "string"
    },
    "passwordResetUrl": {
      "type": "string"
    },
    "claimRequired": {
      "type": "boolean"
    },
    "ownerVerificationRequired": {
      "type": "boolean"
    },
    "requiredFields": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "claim_activation_token": {
      "type": "string"
    },
    "claimActivationToken": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

HTTP 200 response (text/plain)

{
  "type": "string"
}

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

Operation errors: VERIFICATION_RESTART_REQUIRED.

POST /api/license/v1/claim-status

Restore a pending serial claim and receive claim activation material after email verification.

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
  • query format: value. Optional compact HISE transport on successful serial activation or claim-status; default is JSON.
  • instance_id: string (required)
  • machine_id: string
  • product_id: integer
  • plugin_version: string
  • version: string
  • license_key: string (required)
  • claim_id: string
Returns
pending_email_verification, verified with claim_activation_token/claimActivationToken, or identity_required. Inspect status/code and ok; HTTP 200 alone is not activation.
Side effects
Does not activate the machine. The client must call /activate after verified status.
Notes
HTTP 200 may mean pending_email_verification, verified or identity_required; inspect status/code and ok. Only verified returns claim_activation_token for a separate final POST /activate on the same product/serial/machine. 400 VERIFICATION_RESTART_REQUIRED means the link expired or was not sent: submit email and serial to /claim again instead of polling forever. A confirmed owner/access denial is not offline grace. Pending polling/finalization can retry transient outages without discarding the saved claim. GET is a compatibility transport; prefer POST to keep serial/proof out of URLs and logs. A query format=hise_text or hise_text selects compact SSCLAIM text for successful claim-status transport. Default JSON preserves the full response; an HTTP 200 identity/pending state is not activation.
Request, response and error reference

Query and header parameters

[
  {
    "name": "format",
    "in": "query",
    "required": false,
    "schema": {
      "const": "hise_text"
    },
    "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
  }
]

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"
    },
    "claim_id": {
      "type": "string"
    }
  },
  "required": [
    "license_key",
    "instance_id"
  ],
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "claim_id": {
      "type": "string"
    },
    "claimId": {
      "type": "string"
    },
    "emailSent": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "nextAction": {
      "type": "string"
    },
    "passwordResetUrl": {
      "type": "string"
    },
    "claimRequired": {
      "type": "boolean"
    },
    "ownerVerificationRequired": {
      "type": "boolean"
    },
    "requiredFields": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "claim_activation_token": {
      "type": "string"
    },
    "claimActivationToken": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

HTTP 200 response (text/plain)

{
  "type": "string"
}

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

Operation errors: VERIFICATION_RESTART_REQUIRED.

POST /api/license/v1/activate

Activate the current machine after direct serial/customer proof or a verified serial claim.

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
  • query format: value. Optional compact HISE transport on successful serial activation or claim-status; default is JSON.
  • 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
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.
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. A query or body format=hise_text or hise_text selects compact SSACTIVATE text on the successful serial activation branch. Other activation/error branches can still return JSON; format is not a universal content-negotiation guarantee. Default JSON retains the complete response, including any signed offline grant.
Request, response and error reference

Query and header parameters

[
  {
    "name": "format",
    "in": "query",
    "required": false,
    "schema": {
      "const": "hise_text"
    },
    "description": "Optional compact HISE transport on successful serial activation or claim-status; default is JSON."
  }
]

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
}

HTTP 200 response (text/plain)

{
  "type": "string"
}

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

POST /api/license/v1/customer-login/activate

Activate by customer account identity when the product supports account/login activation.

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
  • device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.
  • email: string
  • password: string
  • customer_token: string
  • content_protocol_version: 1 | 2. Use 2 with the matching maintained native package.
  • content_releases: array
  • previous_content_authorization: object
Returns
activation result with validation token, entitlement/customer details, device limit and subscription state where applicable.
Notes
The token branch resolves the verified customer identity from the token. Never persist account passwords or substitute a developer token; product ownership and device checks still apply. The direct email/password compatibility branch cannot complete a two-factor challenge: it returns 401 TWO_FACTOR_REQUIRED for an enabled account. Current JUCE 0.9.3 and HISE Native 0.5.2 clients first call /api/auth/login with role:customer, continue with twoFactorToken/twoFactorCode when requested, then pass the verified customer token as customer_token here. Never substitute the challenge token or a developer session. Entitlement and machine checks still apply. Regenerate and rebuild older packages; see the dedicated customer-login guide for the complete conversation. 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. When account-token session verification is unavailable, fail closed with 503 SESSION_VERIFICATION_UNAVAILABLE. Retry after recovery; do not treat it as authorization or confirmed revocation. A verified revoked account session returns 401 LIBRARY_SESSION_REVOKED. SoundSync-wide customer suspension returns 403 CUSTOMER_ACCOUNT_RESTRICTED, including for an existing shared account session; store closure remains store-scoped. Shared library tokens follow their own token/ownership checks and do not replace required customer-account sign-in.
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"
    },
    "device_credential_supported": {
      "type": "boolean",
      "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias."
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string"
    },
    "customer_token": {
      "type": "string",
      "minLength": 1
    },
    "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,
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "instance_id"
          ]
        },
        {
          "required": [
            "machine_id"
          ]
        }
      ]
    },
    {
      "anyOf": [
        {
          "required": [
            "email",
            "password"
          ]
        },
        {
          "required": [
            "customer_token"
          ]
        }
      ]
    }
  ]
}

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.

Operation errors: CUSTOMER_LOGIN_INVALID, TWO_FACTOR_REQUIRED, EMAIL_VERIFICATION_REQUIRED, SESSION_VERIFICATION_UNAVAILABLE, LIBRARY_SESSION_REVOKED, CUSTOMER_ACCOUNT_RESTRICTED, CUSTOMER_STORE_CLOSED.

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.

POST /api/license/v1/deactivate

Deactivate the authenticated server-side machine activation.

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
  • claim_id: string
  • claim_activation_token: string
  • deviceCredential: string
  • pluginSessionId: string
  • session_id: string
  • sessionId: string
  • soundSyncSessionId: string
  • soundsync_session_id: string
  • validationToken: string
  • new_token: string
  • newToken: string
Returns
status deactivated, code DEVICE_DEACTIVATED, remaining_activations.
Side effects
Confirmed success deactivates the authorized server activation and records its event. The HTTP endpoint does not lock local audio by itself. Clear obsolete activation and grace state only after confirmed server deactivation; retain pending proof and the local block until then. Let the maintained JUCE runtime manage its protected state.
Notes
Send the retained device_credential or permitted plugin_session_id with the same product and machine identity. A supported validation-token proof is a separate compatibility path: send the current validation_token with its serial/email or activation context. Product credential headers, a serial and a machine ID alone are not deactivation proof. Missing or invalid compatibility proof returns 401 deactivate_validation_token_required or deactivate_validation_token_invalid. A nonempty proof field only satisfies the request shape; the server still verifies signature, ownership, product, machine and activation generation. Confirm status/code and deactivation flags before claiming server slot release. JUCE locks locally and preserves pending proof until confirmed; deactivation does not issue a fresh offline grant.
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",
      "minLength": 1
    },
    "token": {
      "type": "string",
      "minLength": 1
    },
    "activationId": {
      "oneOf": [
        {
          "type": "integer",
          "minimum": 1
        },
        {
          "type": "string",
          "pattern": "^[1-9][0-9]*$"
        }
      ]
    },
    "licenseReference": {
      "type": "string"
    },
    "plugin_session_id": {
      "type": "string",
      "minLength": 1
    },
    "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.",
      "minLength": 1
    },
    "license_kind": {
      "type": "string",
      "enum": [
        "serial",
        "email_entitlement"
      ]
    },
    "claim_id": {
      "type": "string"
    },
    "claim_activation_token": {
      "type": "string"
    },
    "deviceCredential": {
      "type": "string",
      "minLength": 1
    },
    "pluginSessionId": {
      "type": "string",
      "minLength": 1
    },
    "session_id": {
      "type": "string",
      "minLength": 1
    },
    "sessionId": {
      "type": "string",
      "minLength": 1
    },
    "soundSyncSessionId": {
      "type": "string",
      "minLength": 1
    },
    "soundsync_session_id": {
      "type": "string",
      "minLength": 1
    },
    "validationToken": {
      "type": "string",
      "minLength": 1
    },
    "new_token": {
      "type": "string",
      "minLength": 1
    },
    "newToken": {
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "instance_id"
      ]
    },
    {
      "required": [
        "machine_id"
      ]
    }
  ],
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "device_credential"
          ]
        },
        {
          "required": [
            "deviceCredential"
          ]
        },
        {
          "required": [
            "plugin_session_id"
          ]
        },
        {
          "required": [
            "pluginSessionId"
          ]
        },
        {
          "required": [
            "session_id"
          ]
        },
        {
          "required": [
            "sessionId"
          ]
        },
        {
          "required": [
            "soundSyncSessionId"
          ]
        },
        {
          "required": [
            "soundsync_session_id"
          ]
        },
        {
          "required": [
            "validation_token"
          ]
        },
        {
          "required": [
            "token"
          ]
        },
        {
          "required": [
            "validationToken"
          ]
        },
        {
          "required": [
            "new_token"
          ]
        },
        {
          "required": [
            "newToken"
          ]
        }
      ]
    }
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "mayOpenProduct": {
      "type": "boolean"
    },
    "activation_deactivated": {
      "type": "boolean"
    },
    "plugin_session_deactivated": {
      "type": "boolean"
    },
    "activation_id": {
      "type": "integer",
      "minimum": 1
    },
    "activationId": {
      "type": "integer",
      "minimum": 1
    },
    "current_activations": {
      "type": "integer",
      "minimum": 0
    },
    "max_activations": {
      "type": "integer",
      "minimum": 0
    },
    "remaining_activations": {
      "type": "integer",
      "minimum": 0
    },
    "serial_status": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

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

Operation errors: deactivate_validation_token_required, deactivate_validation_token_invalid, DEVICE_ACTIVATION_NOT_FOUND.

SoundSync

Related docs

Use these pages for complete plugin licensing implementation.

Plugin Credentials

Credential model and headers.

Test Connection

Credential relationship verification.

Licensing Overview

Activation through deactivation.

SoundSync

Activate an email entitlement with a code

This flow proves access to the email associated with an existing entitlement. It is separate from serial-claim verification and password-based customer-login activation.

POST /api/license/v1/activation/start

Begin email-code activation for a product entitlement

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
  • email: string (required)
  • instance_id: string (required)
  • device_label: string
  • plugin_version: string
Returns
200: ok, status pending_email_verification, code PENDING_EMAIL_VERIFICATION; challengeId, emailSent, and branding can be present.
Notes
Can create a challenge and send an email. The same generic pending state can be returned when access is unavailable; it does not prove entitlement or email delivery.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "instance_id": {
      "type": "string"
    },
    "device_label": {
      "type": "string"
    },
    "plugin_version": {
      "type": "string"
    }
  },
  "required": [
    "email",
    "instance_id"
  ],
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "status": {
      "const": "pending_email_verification"
    },
    "code": {
      "const": "PENDING_EMAIL_VERIFICATION"
    },
    "challengeId": {
      "oneOf": [
        {
          "type": "string",
          "pattern": "^[1-9][0-9]*$"
        },
        {
          "type": "integer",
          "minimum": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "emailSent": {
      "type": "boolean"
    },
    "branding": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "status",
    "code"
  ],
  "additionalProperties": true
}

Documented failures: 400, 403, 500.

POST /api/license/v1/activation/verify-email

Verify the six-digit code and complete email-entitlement activation

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
  • email: string (required)
  • instance_id: string (required)
  • device_label: string
  • plugin_version: string
  • device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.
  • code: string (required)
  • content_protocol_version: 1 | 2. Use 2 with the matching maintained native package.
  • content_releases: array
  • previous_content_authorization: object
Returns
200: activation result if the code and current entitlement/device checks pass.
Notes
Codes expire after 15 minutes and are one-use. Five incorrect attempts lock the challenge. Invalid, expired, missing, or locked codes return 400; product credential and access checks still apply. 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": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "instance_id": {
      "type": "string"
    },
    "device_label": {
      "type": "string"
    },
    "plugin_version": {
      "type": "string"
    },
    "device_credential_supported": {
      "type": "boolean",
      "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias."
    },
    "code": {
      "type": "string",
      "pattern": "^\\d{6}$"
    },
    "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"
      ]
    }
  },
  "required": [
    "email",
    "instance_id",
    "code"
  ],
  "additionalProperties": true
}

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, 403, 500.

Keep the challenge bound to one machine

Use the same customer email, product credentials, and stable instance_id for start and verification. Enter the code into the client; do not treat the initial pending response as an unlocked plugin. After successful verification, keep the returned activation/validation state under the package policy.

Request a fresh code after expiry or a locked challenge. A serial claim link and its claim_activation_token belong to the separate claim flow; do not interchange those tokens with an email-entitlement activation code.

SoundSync

Start email-code activation

Start email-code activation
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/license/v1/activation/start" \
  -H "x-ss-app-id: $APP_ID" \
  -H "x-ss-plugin-key: $PLUGIN_KEY" \
  -H "x-ss-plugin-secret: $PLUGIN_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"email":"customer@example.com","instance_id":"example-machine"}'

SoundSync

Verify the customer-entered code

Verify the customer-entered code
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/license/v1/activation/verify-email" \
  -H "x-ss-app-id: $APP_ID" \
  -H "x-ss-plugin-key: $PLUGIN_KEY" \
  -H "x-ss-plugin-secret: $PLUGIN_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"email":"customer@example.com","instance_id":"example-machine","code":"123456"}'

SoundSync

Native public-client request headers

HeaderValue and purpose
x-ss-app-idThe app ID from this product configuration.
x-ss-product-idThe positive numeric product ID from the same configuration.
x-soundsync-public-clientjuce-native for the generated JUCE client, or hise-native for the generated native HISE client.

SoundSync

Native startup validation request

Native startup validation request
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/license/v1/validate" \
  -H "x-ss-app-id: $APP_ID" \
  -H "x-ss-product-id: $PRODUCT_ID" \
  -H "x-soundsync-public-client: juce-native" \
  -H "Content-Type: application/json" \
  --data '{"instance_id":"example-machine","device_credential":"DEVICE_CREDENTIAL_FROM_AUTHORIZED_RESPONSE","device_credential_supported":true}'

Keep identity and access proof separate

Replace the illustrative device credential and machine ID with values retained after authorized activation. App/product headers identify the application; they do not authorize customer access on their own. Start activation or the supported claim/customer-login flow before validation, and follow the returned denial or reactivation state.

The standard custom-HTTP and HISEScript path instead uses x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret. Do not add those shared secrets to generated native public configuration. Use the generated client for its signed response, token/session, persistence, and audio-enforcement rules rather than treating this curl example as a replacement licensing runtime.

Enroll and retain native renewal proof

The generated JUCE client sends device_credential_supported:true during supported activation and validation. Successful enrollment returns device_credential_status:ready and a private device_credential, alongside the short-lived plugin_session_id and its plugin_session_expires_at when available. Save the newest returned proof using the maintained secure storage. The supported body aliases deviceCredentialSupported and deviceCredential map to the same fields.

A device_credential is product/device-bound renewal proof, not a customer login, library bearer token or signed offline grant. A permitted plugin_session_id or validation_token can also validate within its own lifetime; a short-lived proof is not a durable renewal strategy after a long offline period. Do not copy proof between machines or place it in URLs, logs or public screenshots.

If device_credential_status is pending, enrollment is incomplete even when another part of activation succeeded. JUCE reports device_credential_pending, stays locked and retries enrollment automatically. Do not convert this state into offline-valid access or delete the activation to obtain another slot. A completed online validation may then return a verified offline_lease for the Access period; renewal proof alone cannot unlock offline audio.

SoundSync

Native customer activation with renewal enrollment

Native customer activation with renewal enrollment
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/license/v1/customer-login/activate" \
  -H "x-ss-app-id: $APP_ID" \
  -H "x-ss-product-id: $PRODUCT_ID" \
  -H "x-soundsync-public-client: juce-native" \
  -H "Content-Type: application/json" \
  --data '{"instance_id":"example-machine","customer_token":"CUSTOMER_TOKEN_FROM_SUPPORTED_LOGIN","device_credential_supported":true}'

SoundSync

Native server deactivation request

Native server deactivation request
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/license/v1/deactivate" \
  -H "x-ss-app-id: $APP_ID" \
  -H "x-ss-product-id: $PRODUCT_ID" \
  -H "x-soundsync-public-client: juce-native" \
  -H "Content-Type: application/json" \
  --data '{"instance_id":"example-machine","device_credential":"DEVICE_CREDENTIAL_FROM_AUTHORIZED_RESPONSE"}'

Confirm the deactivation, not only the request

A confirmed response includes status:deactivated, code:DEVICE_DEACTIVATED and activation_deactivated:true; native session deactivation can also report plugin_session_deactivated:true and remaining_activations. No fresh offline grant is issued. Do not treat any HTTP 200 or an unconfirmed body as proof that the device slot was released.

An unavailable/expired plugin session can return 401 plugin_session_invalid on validation. Keep a valid durable device credential for renewal and follow confirmed entitlement/device denials separately. Deactivation can return 404 DEVICE_ACTIVATION_NOT_FOUND; reconcile the actual activation state rather than claiming a successful release. JUCE keeps its local pending block and protected proof until completion. These illustrative requests do not replace that runtime.

Signed offline grants in successful licensing responses

Successful product/device activation or validation may include offline_lease alongside offline_grace_days, grace_expires_at and offline_grace. offline_lease is a signed JSON envelope containing alg, kid, payload and signature; the payload and signature are base64 encoded. Use the generated JUCE verifier and its trusted public-key ring instead of trusting decoded claims alone.

The offline_lease payload binds the issuer, product, activation, device, issue time and expiry. This bounded lease is issued only for an authorized positive grace period; zero or disabled grace does not issue that lease. Explicit signed permanent-device product/content authorization follows its separate ownership policy and is not inferred from a missing expiry. Missing signing configuration or a confirmed denial never creates permission. Do not log or publish a customer grant.

offline_grace.enabled and grace_expires_at describe server policy/deadlines; neither proves that a JUCE client has a valid signed grant. For bounded grace require the opaque offline_lease and trusted bundled public keys. For explicitly authorized permanent-device ownership, use the matching SDK to verify product_authorization and any required content_authorization instead; the absence of an offline_lease alone is not a rejection. A signing-readiness problem can leave online authorization working without issuing a lease; contact SoundSync rather than fabricating offline permission. The selected period begins at successful online activation/validation and is capped by earlier access deadlines.

SoundSync

Ship the offline-capable client

JUCE update guide

Verify capability, rebuild, refresh online and distribute.

Use the serial claim helper for ownership verification

beginClaim(serial, email) starts the existing serial ownership-verification flow. Its first argument is the serial/license key, not an arbitrary web claim token. The wire request sends license_key and the current machine identity to POST /api/license/v1/claim.

A pending claim leaves the plugin locked. Keep the pending serial, email and claim ID in the native licensing flow, then use Restore or pollClaim to check /api/license/v1/claim-status. Once the server returns a claim_activation_token, the client makes the final /api/license/v1/activate request for that same serial and machine. A claim email, verified status or HTTP 200 alone does not unlock the plugin or reserve a device slot.

Pending serial/email context survives a restart in the protected cache. A temporary network failure, server error or rate limit during status checking or final activation keeps the claim pending so Restore can retry. A confirmed licensing denial is different and does not create offline permission.

SoundSync

Serial claim outcomes and recovery

ResultWhat to do
pending_email_verificationKeep the product locked. Save claim_id with the serial, customer email and machine identity. Complete the private verification link, then Restore or poll claim status.
verified + claim_activation_tokenPOST /api/license/v1/activate for the same serial and machine with claim_activation_token. Verification alone is not activation or a device reservation.
400 VERIFICATION_RESTART_REQUIREDThe link was not sent or has expired. Submit the email and serial to /claim again; do not poll the expired claim indefinitely.
503 VERIFICATION_EMAIL_FAILED / emailSent:falseDelivery was not confirmed. Wait for service recovery and deliberately retry the claim, or contact product support. HTTP failure does not grant access.
SERIAL_OWNER_EMAIL_MISMATCH / SERIAL_OWNER_LOGIN_REQUIREDSign in to the owning customer account, verify the owner email where supported, or contact support. Do not replace the owner email or create another identity to bypass the denial.
identity_required / CUSTOMER_DETAILS_REQUIREDProvide the requested identity or use the owner-login path indicated by nextAction. HTTP 200 with ok:false is not a verified claim.
429, timeout or temporary server error while polling/finalizingMaintained native clients keep a pending claim for Restore to retry. Honor retry guidance; do not clear the cache or replace the machine identity merely to retry. No offline grant is created.
Revoked, refunded, expired or product-mismatched serialStop activation and follow the purchase/support path. These are access decisions, not an eligible connectivity failure.

Product and independent content authorization

Maintained JUCE clients send content_protocol_version:2 and bounded content_releases references when protected content is configured. Activation/validation can return product_authorization, content_authorization, unavailable_content, other_major_authorizations and protected activation status. Verify the RS256 envelopes in the matching SDK; pending is not playback permission.

The 64-reference limit is per request. Host-version context expresses software compatibility, not a paid major-version restriction. permanent_device is available only when explicitly authorized by a signed ownership grant; ordinary grace, trials and subscriptions remain bounded.

SoundSync

Protected delivery and integration

Protected Content API

Catalog, private upload publication and native proof.

Existing licensing URLs use the same access checks

The unversioned POST licensing routes below remain active. They call the same activation, validation, deactivation, serial-claim and email-code handlers as their /v1 counterparts. Use the linked /v1 contract for request fields, credentials, status codes and side effects. New integrations should follow the current package and /v1 examples.

An older URL cannot bypass product scope, customer ownership, device proof, revocation, suspension or subscription state. Do not retry a mutation through the other URL as though it were a new operation. Changing a URL alone does not upgrade a shipped package, install a signing public key or add offline grace.

SoundSync

Unversioned licensing operation map

MethodCompatibility pathContract or result
POST/api/license/activatePOST /api/license/v1/activate
POST/api/license/validatePOST /api/license/v1/validate
POST/api/license/deactivatePOST /api/license/v1/deactivate
POST/api/license/claimPOST /api/license/v1/claim
POST/api/license/claim-statusPOST /api/license/v1/claim-status
POST/api/license/activation/startPOST /api/license/v1/activation/start
POST/api/license/activation/verify-emailPOST /api/license/v1/activation/verify-email

SoundSync

Diagnostic and email-link routes

GET /api/license/ping

Inspect parsed app identity and key length without authenticating

Auth
Public request; operation-specific verification still applies
Scope
Public diagnostic parsing only; no product credential or customer authorization is verified.
Request fields
  • header x-ss-app-id: string
Returns
HTTP 200: ok, saw.
Notes
Returns ok:true with parsed saw.appId (default soundsync) and saw.appKey_len. It does not validate the key, record plugin verification, activate a machine, issue a grant or establish current licensing health. Do not send real secrets just to test reachability; an empty-key response is expected without credentials.
Request, response and error reference

Query and header parameters

[
  {
    "name": "x-ss-app-id",
    "in": "header",
    "required": false,
    "schema": {
      "type": "string"
    }
  }
]

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "const": true
    },
    "saw": {
      "type": "object",
      "properties": {
        "appId": {
          "type": "string"
        },
        "appKey_len": {
          "type": "integer"
        }
      },
      "additionalProperties": true,
      "required": [
        "appId",
        "appKey_len"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "ok",
    "saw"
  ]
}
GET /api/license/verify-license

Consume an emailed serial-claim token and return HTML

Auth
Public request; operation-specific verification still applies
Scope
The emailed private verification token authorizes claim confirmation; this is not an account Bearer session or activation proof.
Request fields
  • query token: string (required). Private serial-claim email token; never log or share the URL.
Returns
HTTP 200: text/html.
Notes
Consumes the serial-claim verification token and returns an HTML result, not JSON or a plugin validation token. The root /verify-license browser link calls the same handler. Missing/invalid tokens return 400 HTML; expired tokens return 410 HTML. This GET can confirm a claim and is not a read-only health probe. Return to the plugin, check claim-status and perform the separate final activation on the same product and machine. Email verification alone does not grant offline access.
Request, response and error reference

Query and header parameters

[
  {
    "name": "token",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "Private serial-claim email token; never log or share the URL."
  }
]

No request body fields are read by this operation.

HTTP 200 response (text/html)

{
  "type": "string"
}

Documented failures: 400, 410, 500.

Ping is reachability, not authentication

GET /api/license/ping returns ok:true and saw:{appId,appKey_len}. It parses the optional app identity and key length without authenticating them; appId defaults to soundsync. A successful ping is not recorded plugin verification, activation, validation, current licensing health or an offline grant. Test reachability without sending private keys.

An email link confirms a claim, not a machine activation

GET /api/license/verify-license?token=... and the browser link /verify-license share the serial-claim verifier. The private emailed token is consumed and the response is HTML: 200 for success, 400 for missing/invalid proof and 410 for expiry. This GET can change claim state, so do not poll it as a health check or expose its URL in logs.

After confirmation, the plugin checks claim-status and performs final activation with the verified proof for the same product, serial and machine. The verification page does not return an account session, validation token, device credential or signed offline grant.

Compact HISE responses are a transport option

JSON is the default for current clients. A successful serial activation can use format=hise_text or hise_text in the query or body to return SSACTIVATE text. Claim-status accepts the same query switches and returns SSCLAIM text. Other activation branches and errors can still return JSON. A compact transport is not a different licensing model; native clients needing the complete signed offline response should retain the maintained JSON conversation.

Require the authorization for the selected offline mode

Bounded grace requires a valid signed offline_lease with its product, activation, device and deadline checks. Explicit permanent-device ownership instead uses signed product_authorization and any required content_authorization verified by the matching protocol-2 SDK. A missing offline_lease alone is not a failure for that explicitly authorized ownership mode.

A device credential renews authorized access online; it is not itself offline playback permission. Pending enrollment, an unsigned cached date and a successful catalog read cannot substitute for a verified grant. Package regeneration still requires integrating, rebuilding and distributing the matching plugin; changing an API URL does not update installed binaries.