API Reference

Product Credentials API

Developer-authenticated API reference for creating, ensuring, revealing, rotating, and revoking product-scoped plugin credentials.

Start with getting started Explore API docs

POST /activateGET /validatePOST /deactivate

Product credentials
Activation request
Entitlement check
Device registration
Periodic validation
Deactivation when needed

Auth boundary

These endpoints require a developer dashboard/user JWT. They do not accept product plugin credentials, and product plugin clients must not call these management endpoints. Generated plugin packages should call Test Connection and licensing endpoints only.

SoundSync

Management endpoints

The platform route catalog registers these product-scoped credential management endpoints.

GET /api/developer/plugin-keys/products

List product-scoped plugin credentials visible to the authenticated developer, optionally filtered by productId.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: productId query optional
Returns: ok, credentials[], count. Credential records include appId, pluginKeyPreview, pluginSecretPreview, apiBaseUrl, status, isActive, lastUsedAt, rotated/revoked metadata, and one-time reveal metadata.

GET /api/developer/plugin-keys/products/:productId

Fetch the active product credential/status for one developer-owned product.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: productId path parameter
Returns: ok, credential, status/active state, credential previews and metadata.
Side effects: None.

POST /api/developer/plugin-keys/products/:productId

Create the first active product credential for a product.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: reason optional
metadata optional
Returns: 201 ok, credential, created true, one_time_reveal with appId, pluginKey, pluginSecret, and secret_shown_once true.
Side effects: Inserts a product credential row with hashed key/secret and recoverable secret ciphertext when the runtime key is available.
Notes: If an active credential already exists, the platform returns ACTIVE_CREDENTIAL_EXISTS with HTTP 409. Use ensure or rotate intentionally instead.

POST /api/developer/plugin-keys/products/:productId/ensure

Return the current active credential, or create one if missing.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: reason optional
metadata optional
Returns: ok, credential and created flag. New credentials include one_time_reveal; existing credentials return previews only.
Side effects: May create a credential when none exists.

POST /api/developer/plugin-keys/products/:productId/reveal-secret

Reveal a recoverable active credential secret to an authenticated product owner.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: reason optional
metadata optional
Returns: ok, one_time_reveal/revealed credential material with appId, pluginKey, pluginSecret, and productKey/ProductSecret compatibility aliases.
Side effects: Records explicit reveal intent through controller/service metadata.
Notes: Older unrecoverable credentials return PRODUCT_CREDENTIAL_SECRET_UNAVAILABLE with rotate-key and rotate-secret recovery endpoints.

POST /api/developer/plugin-keys/products/:productId/rotate-key

Rotate the active product credential pair when a package or integration key needs replacement.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: reason optional
metadata optional
Returns: 201 ok, credential, one_time_reveal, previous_credential, rotated true.
Side effects: Revokes the previous active credential and inserts a replacement credential. Regenerate packages after this.

POST /api/developer/plugin-keys/products/:productId/rotate-secret

Rotate the active product credential pair when the secret is exposed, lost, or unrecoverable.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: reason optional
metadata optional
Returns: 201 ok, credential, one_time_reveal, previous_credential, rotated true.
Side effects: Revokes the previous active credential and inserts a replacement credential. The current implementation replaces the pair for both key and secret rotation.

POST /api/developer/plugin-keys/products/:productId/revoke

Revoke the active product credential for a product.

Auth: Developer dashboard/user JWT via Authorization: Bearer <developer-session-token>. Product plugin credentials are not accepted for management endpoints.
Scope: Developer-owned product credential management. Admin users may have broader operator visibility according to platform ownership checks.
Request fields: reason optional
metadata optional
Returns: ok, revoked true/false and credential status.
Side effects: Marks the active credential inactive/revoked. Existing packages using that credential should fail Test Connection or product credential auth until regenerated with a new active credential.

SoundSync

Lifecycle states

Use this lifecycle when setting up, shipping, and recovering package credentials.

Step	Surface	Auth	Important behavior
Create	POST /api/developer/plugin-keys/products/:productId	Developer JWT	Returns full App ID, plugin key, and plugin secret once in one_time_reveal.
Ensure	POST /api/developer/plugin-keys/products/:productId/ensure	Developer JWT	Safe setup call. Existing credentials return previews, not the full secret.
Embed in package	Generated HISE package or custom config	No management call from plugin	Runtime config contains App ID, plugin key, plugin secret, product ID, developer ID, environment, and API base URL.
Verify	POST /api/plugin-connections/verify	Credential body fields	Confirms productId/appId/pluginKey/pluginSecret belong together before activation testing.
Use for licensing	/api/license/v1/*	Product credential headers	Custom clients send x-ss-app-id, x-ss-plugin-key, and x-ss-plugin-secret.
Reveal	POST /api/developer/plugin-keys/products/:productId/reveal-secret	Developer JWT	Only for recoverable current credentials. Unrecoverable credentials return PRODUCT_CREDENTIAL_SECRET_UNAVAILABLE.
Rotate	POST /rotate-key or /rotate-secret	Developer JWT	Revokes the previous pair and returns a replacement one-time reveal. Regenerate HISE packages and update custom configs.
Revoke	POST /revoke	Developer JWT	Invalidates packages using that active credential; create or ensure a new credential before shipping an updated package.

SoundSync

Create and rotate examples

The examples use fake demo identifiers and omit real customer or production data.

Create curl

curl -sS -X POST "$SOUNDSYNC_API_BASE/api/developer/plugin-keys/products/prod_demo_piano" \
  -H "Authorization: Bearer $DEVELOPER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"reason":"initial_package_setup"}'

One-time reveal json

{
  "ok": true,
  "created": true,
  "credential": {
    "productId": "prod_demo_piano",
    "appId": "ss_prod_demoapp",
    "pluginKeyPreview": "ss_pk_demo...",
    "pluginSecretPreview": "ss_ps_demo...",
    "status": "active",
    "hasRecoverableSecret": true
  },
  "one_time_reveal": {
    "appId": "ss_prod_demoapp",
    "pluginKey": "ss_pk_demo",
    "pluginSecret": "ss_ps_demo",
    "secret_shown_once": true
  }
}

Rotate secret curl

curl -sS -X POST "$SOUNDSYNC_API_BASE/api/developer/plugin-keys/products/prod_demo_piano/rotate-secret" \
  -H "Authorization: Bearer $DEVELOPER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"reason":"secret_exposed_in_support_log"}'

SoundSync

Security boundary

Keep developer management credentials separate from client-distributed product credentials.

Value	Where it belongs	Rule
Developer JWT	Used only for dashboard/user credential management endpoints.	Do not embed in plugins, packages, installers, examples, or customer-visible config.
App ID	Client-distributable product identifier, for example ss_prod_demoapp.	Not a secret and not the Product ID. It must still match the plugin key and secret.
Plugin key	Client-distributable credential factor, for example ss_pk_demo.	Treat as sensitive in logs. It can be transported as x-ss-plugin-key, Bearer compatibility, or x-ss-api-key compatibility only where documented.
Plugin secret	Second client credential factor, for example ss_ps_demo.	Never ask a customer to type it. Never log it. Rotate immediately if it appears in public support tickets, screenshots, or telemetry.
Legacy developer keys	Developer-level plugin key creation and secret reveal return 410.	Use product-scoped credentials instead. Legacy fallback remains compatibility only and must not be documented as the current model.

API reference

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

GET/POST

Product Credentials API

/docs/api/product-credentials

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