Skip to content
SoundSyncAudio software platform

Guide

SoundSync API Reference

Licensing, customer access, commerce, partner programs, marketing, and developer operations organized by authentication and workflow.

Start with getting startedExplore API docs

Start with the identity and the operation

Plugin product credentials, native public-client identity, customer sessions, developer JWTs, and external partner keys authorize different operations. Select the reference for the task rather than substituting another token.

Endpoint references describe current routes and service behavior. Copyable examples identify their fixture or illustrative status; a documented route is not a universal live-provider or native-runtime guarantee.

SoundSync

Current contracts and operation coverage

Authentication models

Standard product credentials versus native public-client and customer proof.

Explore

Current operation map

Packages, uploads, WooCommerce, marketing, promotions, marketplace, and test-only installments.

Explore

SoundSync

Refunds, recipient programs, and automation

Developer refunds

Original-payment preview, whole-product selection, confirmation, and operation states.

Explore

Affiliate and collaborator programs

Agreements, live consent, attribution, balances, and destination setup.

Explore

Growth flows

Sequences, test sends, suppression, queue, and trigger activity.

Explore

Keep-your-products bundles

Paid invoice ownership and refund/dispute effects.

Explore

SoundSync

Reference pages

Start with authentication and licensing for native plugin integrations.

Authentication

Product plugin credential headers and compatibility aliases.

Explore

Plugin Connection Verification

POST /api/plugin-connections/verify.

Explore

Licensing

Claim, claim-status, activate, customer-login activate, validate, and deactivate.

Explore

Product Credentials

Credential concepts and status.

Explore

Errors

Stable codes and client behavior.

Explore

SoundSync

Plugin endpoint contracts

Read the operation fields, authentication, outcomes, and related retry/grace guides together. Source-reviewed examples are not a live transcript or proof of every client environment.

POST /api/plugin-connections/verify

Verify the standard product credential tuple or supported native public-client app/product identity before customer activation testing.

Auth
JSON body credential check. Headers are not used for this endpoint.
Scope
Product, app, credential, environment, and machine scoped.
Request fields
  • productId: integer (required)
  • appId: string (required)
  • pluginKey: string
  • pluginSecret: string
  • publicClient: hise-native | juce-native
  • pluginVersion: string
  • environment: string
Returns
ok/connected, productId, credentialId, pluginVersion, environment, lastSeenAt.
Side effects
Updates credential last-used state, upserts plugin connection status, and records a plugin connection event.
Notes
This endpoint reads its JSON body rather than substituting licensing headers. The native public-client path does not require a distributed pluginSecret. Connectivity/product identification is not customer entitlement or audio unlock.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "appId": {
      "type": "string"
    },
    "pluginKey": {
      "type": "string"
    },
    "pluginSecret": {
      "type": "string"
    },
    "publicClient": {
      "enum": [
        "hise-native",
        "juce-native"
      ]
    },
    "pluginVersion": {
      "type": "string"
    },
    "environment": {
      "type": "string"
    }
  },
  "required": [
    "productId",
    "appId"
  ],
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": true
}
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
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.
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"
    }
  }
]

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: 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
  • 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.
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"
    },
    "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
}

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
  • instance_id: string
  • machine_id: string
  • product_id: integer
  • plugin_version: string
  • version: string
  • license_key: string
  • serial: string
  • email: string
  • validation_token: string
  • token: string
  • activationId: value
  • licenseReference: string
  • plugin_session_id: string
  • device_credential: string. Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio.
  • license_kind: serial | email_entitlement
  • device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.
  • claim_id: string
  • claim_activation_token: string
Returns
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. Only an authorized signed offline_lease can support JUCE offline access.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "instance_id": {
      "type": "string"
    },
    "machine_id": {
      "type": "string"
    },
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "plugin_version": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "license_key": {
      "type": "string"
    },
    "serial": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "validation_token": {
      "type": "string"
    },
    "token": {
      "type": "string"
    },
    "activationId": {
      "oneOf": [
        {
          "type": "integer",
          "minimum": 1
        },
        {
          "type": "string",
          "pattern": "^[1-9][0-9]*$"
        }
      ]
    },
    "licenseReference": {
      "type": "string"
    },
    "plugin_session_id": {
      "type": "string"
    },
    "device_credential": {
      "type": "string",
      "description": "Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio."
    },
    "license_kind": {
      "type": "string",
      "enum": [
        "serial",
        "email_entitlement"
      ]
    },
    "device_credential_supported": {
      "type": "boolean",
      "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias."
    },
    "claim_id": {
      "type": "string"
    },
    "claim_activation_token": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "instance_id"
      ]
    },
    {
      "required": [
        "machine_id"
      ]
    }
  ]
}

HTTP 200 response (application/json)

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

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

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
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.7.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. 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. Shared library tokens follow their own token/ownership checks.
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
    }
  },
  "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."
    }
  },
  "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.

POST /api/license/v1/validate

Validate cached activation state on startup or during periodic revalidation.

Auth
x-ss-app-id + x-ss-plugin-key + x-ss-plugin-secret OR x-ss-app-id + x-ss-product-id + x-soundsync-public-client (matching generated native client)
Scope
Product, app, credential, environment, and machine scoped.
Request fields
  • instance_id: string
  • machine_id: string
  • product_id: integer
  • plugin_version: string
  • version: string
  • license_key: string
  • serial: string
  • email: string
  • validation_token: string
  • token: string
  • activationId: value
  • licenseReference: string
  • plugin_session_id: string
  • device_credential: string. Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio.
  • license_kind: serial | email_entitlement
  • device_credential_supported: boolean. Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias.
  • claim_id: string
  • claim_activation_token: string
Returns
active/denied state, rotated validation token, last validation timestamps, offline grace fields, subscription/license state.
Side effects
Refreshes validation state and token when allowed. Explicit denials force lock and must not use offline grace.
Notes
Generated native clients request device_credential_supported:true and retain the returned device_credential, plugin_session_id and newest validation_token privately. Device proof can renew after a short-lived token/session expires, but never bypasses revoked access, product/device binding or entitlement checks. device_credential_status:pending is incomplete enrollment, not an offline grant. Only an authorized signed offline_lease can support JUCE offline access.
Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "instance_id": {
      "type": "string"
    },
    "machine_id": {
      "type": "string"
    },
    "product_id": {
      "type": "integer",
      "minimum": 1
    },
    "plugin_version": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "license_key": {
      "type": "string"
    },
    "serial": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "validation_token": {
      "type": "string"
    },
    "token": {
      "type": "string"
    },
    "activationId": {
      "oneOf": [
        {
          "type": "integer",
          "minimum": 1
        },
        {
          "type": "string",
          "pattern": "^[1-9][0-9]*$"
        }
      ]
    },
    "licenseReference": {
      "type": "string"
    },
    "plugin_session_id": {
      "type": "string"
    },
    "device_credential": {
      "type": "string",
      "description": "Private renewal proof returned by authorized enrollment; deviceCredential is an accepted body alias. Bind to the same app/product and instance_id. It cannot independently unlock offline audio."
    },
    "license_kind": {
      "type": "string",
      "enum": [
        "serial",
        "email_entitlement"
      ]
    },
    "device_credential_supported": {
      "type": "boolean",
      "description": "Send true to request native renewal-credential enrollment. deviceCredentialSupported is an accepted body alias."
    },
    "claim_id": {
      "type": "string"
    },
    "claim_activation_token": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "instance_id"
      ]
    },
    {
      "required": [
        "machine_id"
      ]
    }
  ]
}

HTTP 200 response (application/json)

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

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

POST /api/license/v1/deactivate

Deactivate this machine and release local access.

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
Sets deactivated_at on the activation, records an event, and should cause the client to delete local activation 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

Package and ownership references

HISE Package API

Generation, status, rotation, and separate storefront packages.

Explore

Subscription models

Lease access versus permanent ownership from a subscription bundle.

Explore

Refund API

Preview, confirmation, whole-product selection, and recovery.

Explore

SoundSync

New workflow references

Catalog importing

Product discovery, mappings, draft commits, and delivery links.

Explore

Private uploads

Resumable uploads and signed package ZIP links.

Explore

Brand section saves

Versioned identity, visuals, and support.

Explore

Campaign delivery review

Safe failures and uncertain provider acceptance.

Explore

Subscription recovery

Renewal pricing, payment updates, and access deadlines.

Explore

Set the public API origin

Set SOUNDSYNC_API_BASE=https://www.soundsync.dev before running the shell examples. Examples using SOUNDSYNC_ORIGIN use the same origin. Use the authentication specified for each operation: a developer JWT, customer token, partner key, and product credential are not interchangeable.

SoundSync

Download the current API description

OpenAPI JSON

Machine-readable operations from the current public reference. Request fields, source boundaries, and access scope accompany each operation.

Explore

Read schema coverage before generating a client

Every operation in this public reference now includes reviewed request/response fields or an explicit transport contract. Open an operation to see its JSON schema, query parameters, authentication, response status and documented failures. Required confirmations, accepted aliases and conditional outcomes are explained alongside the fields.

The schemas describe the reviewed public fields, not every internal column or a guarantee that all runtime/provider outcomes have been exercised. A referral or authorized file download can return a redirect; a PDF or CSV call returns a file; refund acceptance is not final provider completion. Keep the linked workflow guide beside any generated client.

SoundSync

Choose the reference depth you need

ReferenceWhat you can rely on
Operation guideMethod, route, purpose, authentication, resource scope, side effects and linked workflow.
Request and response referenceReviewed JSON fields or explicit file/redirect contracts for every operation listed here. Read conditional rules and aliases before calling.
Examples and fixturesEach example covers its stated flow. Source review and synthetic tests do not establish live provider delivery, every renewal/refund state or every native host.

SoundSync

Manage the full product workflow

Product Management API

Drafts, publication, files and reviewed AI suggestions.

Explore

Developer Onboarding API

Resumable account setup, business, selling experience and readiness.

Explore

Reseller Partner Portal API

Membership, relationship records, conversations and approved store connections.

Explore

Partner Hub Management API

Relationships, product assignments, serial inventory, conversations and retired write boundaries.

Explore

Customer and Serial Management API

Current inventory, imports, access actions and purchase tables.

Explore

Domain Setup API

Provider instructions, DNS checks, progress and sender identity.

Explore

API Surfaces and Coverage

Public integrations versus first-party and internal operations.

Explore

Expansion API

Parent requirements and owned-product relationships.

Explore

Support Content API

Contact routing, articles and assistance settings.

Explore

Rent-to-Own Agreement API

Installment history, buyer ownership and cancellation.

Explore

Licensing Rules and Delivery API

Rules, file versions, activity and connection diagnostics.

Explore

Operational AI Draft API

Suggestions, persistence and review status.

Explore

Storefront Management API

Website configuration, catalog placements and AI drafts.

Explore

Brand Assets API

Public uploads, link checks and sender tests.

Explore

Embedded Content API

Published pages, bundles and customer pricing previews.

Explore

SoundSync

Review, reporting and product access

Review Import API

Preview, confirmation, row outcomes and publication.

Explore

Revenue and Activity API

Read-only reporting, shares and recorded payment issues.

Explore

Product Dashboard API

Permission-filtered product overviews.

Explore

SoundSync

Account API reference

Accounts and recovery

Registration, reset, sign-out and verified profile changes.

Explore

SoundSync

Offers, grants and setup checks

Promo Codes and Manual Grants API

Discounts, limits, customer access and subscription grant boundaries.

Explore

Readiness API

Private setup diagnostics, blockers and next actions.

Explore

Workspace Dashboard API

Permission-filtered launch/command center and monthly goals.

Explore

SoundSync

Package activity

Plugin telemetry

Open/click activity, body authentication and safe diagnostics.

Explore

API reference

Endpoint groups are organized by authentication model, product scope, request shape, response shape, errors, idempotency, and integration surface.

POST/GET

Plugin Licensing API

/docs/api/licensing

Verified plugin connection, serial claim, activation, validation, customer-login activation, and deactivation endpoints.

GET/POST

Product Credentials API

/docs/api/product-credentials

Developer-authenticated product credential creation, ensure, reveal, rotation, and revocation endpoints.

GET/POST

Customer Library API

/docs/api/customer-library

Customer-token library listing, webview-library, claim, and expansion/review boundaries.

GET/PUT

Subscriptions API

/docs/api/subscriptions

Beta product subscription settings and subscription state behavior.

GET/POST

Storefront and Embed API

/docs/api/storefront-embed

Hosted storefront and embedded storefront bootstrap/frame-token/cart handoff.

GET/POST/PATCH/DELETE

Partner API

/docs/api/reseller-partner

Controlled partner products, orders, licenses, campaigns, and webhooks.

GET/POST/PATCH/DELETE

Webhooks API

/docs/api/webhooks

Partner webhook subscriptions, delivery events, and signatures.

GET/POST

Checkout API

/docs/api/checkout

Product checkout, quote, tax jurisdiction, and embed handoff.

GET/POST

Orders API

/docs/api/orders

Developer-visible order reporting and partner refund routes.

GET/POST/PATCH

Promotions API

/docs/api/promotions

Promo codes, scheduled deals, and promotion offers.

GET/POST

Marketplace API

/docs/api/marketplace

Public marketplace search and developer list/unlist.

GET

Analytics API

/docs/api/analytics

Developer analytics, revenue, activity, and exports.

GET/POST

Billing API

/docs/api/billing

Developer billing, statements, invoices, settlements, and payouts.

GET/POST/PATCH

Email Marketing API

/docs/api/email-marketing

Contacts, campaigns, automation, and usage.

GET/POST/PATCH/DELETE

Team Accounts API

/docs/api/team-accounts

Developer workspace membership, invitations, roles, product scope, session access, and audit records. Source-reviewed contracts; see the endpoint evidence.

GET/POST/PUT/PATCH

Subscription Bundles API

/docs/api/subscription-bundles

Bundle checkout, customer plan preview/confirmation, scheduled changes, billing setup, and developer definitions/reporting. Lifecycle evidence is operation-specific.

GET/POST

Developer Refund API

/docs/api/refunds

Preview and confirm full-order or whole-product refunds with original payment, tax, share, and access checks.

GET/POST/PATCH

Affiliate and Collaborator API

/docs/api/partner-programs

Agreement management, invitation acceptance, live consent, referral links, accounting, and recipient payout setup.

GET/POST/PATCH

Growth Flow and Automation API

/docs/api/growth-flows

Flow lifecycle, sequence previews, developer-only tests, queue activity, suppression rules, and trigger signals.

GET / POST

HISE Package Management

/docs/api/hise-packages

Developer-authenticated HISEScript, native HISE, and storefront package operations.

GET / POST

Catalog Imports

/docs/api/catalog-imports

Create, inspect, advance, review, and commit catalog jobs, then attach permitted private delivery files.

GET / PUT

Branding Workspaces

/docs/api/branding-workspaces

Read and save Identity, Visuals, or Support without overwriting unrelated brand settings.

GET / POST / PUT / PATCH / DELETE

Product Management API

/docs/api/products

Create drafts, save product sections, publish, manage delivery metadata and inspect product AI drafts.

GET / POST / PUT / PATCH / DELETE

Customer and Serial Management API

/docs/api/customer-management

Current developer customer tables, serial inventory, imports, purchase history and manual access grants.

GET / POST / PUT / PATCH / DELETE

Partner Hub Management API

/docs/api/partner-management

Manage reseller relationships, product assignments, serial inventory and conversations with developer workspace authentication.

GET / POST / PUT / PATCH / DELETE

Developer Onboarding API

/docs/api/developer-onboarding

Resume account setup, save business and selling choices, inspect domain readiness and complete onboarding.

GET / POST / PUT / PATCH / DELETE

Reseller Partner Portal API

/docs/api/partner-portal

Read reseller memberships and relationships, manage approved conversations and review external-sale records.

GET / POST / PUT / PATCH / DELETE

Domain Setup API

/docs/api/domain-setup

Complete the guided domain workflow, DNS checks, sender identity and setup history.

GET / POST / PUT / PATCH / DELETE

API Surfaces and Coverage

/docs/api/surface-coverage

Distinguish integration APIs, authenticated management calls, provider callbacks and internal administration.

GET / POST / PUT / PATCH / DELETE

Expansion and Product Relationship API

/docs/api/expansions

Link expansion products, inspect parent requirements and maintain same-developer product relationships.

GET / POST / PUT / PATCH / DELETE

Support Content API

/docs/api/support

Configure support contact routing, published articles, escalation copy and optional assistance settings.

GET / POST / PUT / PATCH / DELETE

Rent-to-Own Agreement API

/docs/api/rent-to-own

Inspect installment agreements and cancel an owned agreement without initiating a new charge.

GET / POST / PUT / PATCH / DELETE

Operational AI Draft API

/docs/api/operational-ai

Request support replies, analytics explanations, promotion plans and automation ideas for human review.

GET / POST / PUT / PATCH / DELETE

Storefront Management API

/docs/api/storefront-management

Configure the hosted storefront, arrange products, test newsletter delivery and review website AI drafts.

GET / POST / PUT / PATCH / DELETE

Brand Assets and Verification API

/docs/api/branding-assets

Upload brand images, check configured links and test domain-linked email identity.

GET / POST / PUT / PATCH / DELETE

Embedded Storefront Content API

/docs/api/embed-content

Read published pages, templates, support, products and bundle ownership previews.

GET / POST

Review Import API

/docs/api/review-imports

Preview mapped review rows, confirm an import, and inspect private product review records.

GET / POST

Revenue and Activity Reporting API

/docs/api/revenue-reporting

Read sale results, recorded payment issues, current charges and marketplace/share records without moving funds.

GET / POST

Product Dashboard API

/docs/api/product-dashboard

Load a product overview while honoring separate sales, review, file and credential permissions.

GET / POST / PUT

Accounts and Recovery API

/docs/api/accounts

Registration, verification, session identity, password recovery, profile changes and current-password changes.

GET / POST / PUT

Promo Codes and Manual Grants API

/docs/api/promotions-and-grants

Manage product promo codes and grant customer access without confusing a grant with a paid checkout.

GET / POST / PUT

Readiness API

/docs/api/readiness

Read setup blockers, warnings and next actions for accounts, products and storefronts.

GET / POST / PUT

Workspace Dashboard API

/docs/api/workspace-dashboard

Read workspace launch checks, business aggregates and monthly goals with section-level team permissions.

POST

Plugin Telemetry API

/docs/api/plugin-telemetry

Record package UI activity without confusing caller-reported telemetry with customer licensing proof.