Architecture page
HISE Server Conversations
Understand which requests check credentials, claim ownership, activate a device, or open customer access.
SoundSync
Requests have different jobs
| Conversation | Meaning | Does not prove |
|---|---|---|
| Test Connection | Product credential connectivity | Customer entitlement or audio access |
| Claim / email verification | Customer ownership proof for a supported serial flow | A device has been activated |
| Activate | Register authorized product access on the device | Unlimited future device use |
| Validate | Refresh entitlement and machine authorization | A failed network call is permission |
| Deactivate | Release the selected device activation | A purchase was refunded |
| Branding | Retrieve supported product/store visual configuration | Generated local assets are always dynamically updated |
| Library token / WebView library | Open the authenticated customer access surface | A developer session should be shipped in the plugin |
Debug the stage that failed
Record the operation, error code, package variant/version, product ID, and safe environment context. Do not log the secret, serial, password, customer token, or a complete customer record.
The licensing endpoint reference documents request authentication and fields. An unverified response example should not be treated as a tested transcript of a HISE runtime session.
SoundSync
Deactivated state
The supplied deactivation capture shows the product returning to the activation-required flow after device access changes.
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.
/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, customer email, and machine identity.
- 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.
/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
- Same product, email, and machine as the challenge.
- 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)
- 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.
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}$"
}
},
"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."
}
},
"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.