API reference
Accounts and Recovery API
Registration, verification, session identity, password recovery, profile changes and current-password changes.
Account identity and workspace access are different
An account token identifies a signed-in user. Developer permissions, assigned products, customer ownership and intended-recipient invitations are still checked by the relevant operation. Never substitute a developer JWT, library token, partner credential or product key for one another.
SoundSync
Find the account security controls
Account settings brings two-factor status, recovery-code counts, sessions and password changes together. The example shows empty password fields and no setup keys or recovery codes.
SoundSync
Account lifecycle operations
/api/auth/register
Create an account with email verification or a verified popup setup proof
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- email: string (required)
- password: string (required)
- firstName: string
- lastName: string
- role: customer | developer
- account_type: customer | platform
- storefrontSlug: string
- popupClaimToken: string. Private verified popup proof for customer account setup after the reward is awarded. Requires the same email and storefrontSlug. Never log or persist this token in browser storage.
- company_name: string
- website_url: string
- support_email: string
- support_url: string
- business_address: string
- tax_id: string
- brand_color: string
- dark_mode: boolean
- custom_domain: string
- billing_email: string
- partnerInviteToken: string
- programInviteToken: string
- marketingOptIn: boolean
- marketingOptOut: boolean
- logo: string
- teamInviteToken: string
- Returns
- HTTP 202: ok, code, status, emailVerificationRequired, emailSent, message, user.
- Notes
- Ordinary registration returns 202 and creates an unverified account. A valid popupClaimToken creates a verified customer account and returns 200 ACCOUNT_READY without sending a second verification email. The proof must be unexpired, unconsumed and bound to the same email and required storefrontSlug; existing accounts return 409 and should sign in. Neither response creates a signed-in session. The optional logo is a multipart file. Account role and invitations are validated by the server; protected signup configurations can reject registration. A failed marketing-choice save can return 503 with accountCreated: true; do not create another account. A valid teamInviteToken preserves the private developer invitation through developer signup and verification; it is not customer membership or acceptance of the invitation.
Request, response and error reference
Request (application/json or multipart/form-data)
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"customer",
"developer"
]
},
"account_type": {
"type": "string",
"enum": [
"customer",
"platform"
]
},
"storefrontSlug": {
"type": "string"
},
"popupClaimToken": {
"type": "string",
"description": "Private verified popup proof for customer account setup after the reward is awarded. Requires the same email and storefrontSlug. Never log or persist this token in browser storage."
},
"company_name": {
"type": "string"
},
"website_url": {
"type": "string"
},
"support_email": {
"type": "string",
"format": "email"
},
"support_url": {
"type": "string"
},
"business_address": {
"type": "string"
},
"tax_id": {
"type": "string"
},
"brand_color": {
"type": "string"
},
"dark_mode": {
"type": "boolean"
},
"custom_domain": {
"type": "string"
},
"billing_email": {
"type": "string",
"format": "email"
},
"partnerInviteToken": {
"type": "string"
},
"programInviteToken": {
"type": "string"
},
"marketingOptIn": {
"type": "boolean"
},
"marketingOptOut": {
"type": "boolean"
},
"logo": {
"type": "string",
"format": "binary"
},
"teamInviteToken": {
"type": "string"
}
},
"required": [
"email",
"password"
],
"additionalProperties": true
}
HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"code": {
"type": "string"
},
"status": {
"type": "string"
},
"emailVerificationRequired": {
"type": "boolean"
},
"emailSent": {
"type": "boolean"
},
"message": {
"type": "string"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"role": {
"type": "string"
},
"is_reseller": {
"type": "boolean"
},
"phone": {
"type": [
"string",
"null"
]
},
"avatarUrl": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/auth/verify-email
Consume an account verification link and display HTML
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- query token: string (required)
- query storefrontSlug: string
- query program_invite: string
- Returns
- HTTP 200: text/html.
- Notes
- Consumes a private one-use verification token. GET and ordinary POST requests return HTML. POST with Accept:application/json returns verified:true, signInRequired:true and the supported loginUrl; missing/expired/used tokens return 400 INVALID_VERIFICATION_TOKEN JSON and unexpected failure returns 500 VERIFICATION_FAILED JSON. Successful verification does not create a signed-in session. A separately TXT-verified external website can receive the email at its saved callback; arbitrary supplied return destinations are not accepted. Never poll, log or share a verification URL.
Request, response and error reference
Query and header parameters
[
{
"name": "token",
"in": "query",
"schema": {
"type": "string"
},
"required": true,
"description": ""
},
{
"name": "storefrontSlug",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "program_invite",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (text/html)
{
"type": "string"
}
Documented failures: 400, 500.
/api/auth/verify-email
Consume an account verification token with HTML or requested JSON response
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- header Accept: string. Send application/json for the server-to-server verification response; otherwise HTML is returned.
- token: string (required)
- storefrontSlug: string
- program_invite: string
- Returns
- HTTP 200: text/html.
- Notes
- Consumes a private one-use verification token. GET and ordinary POST requests return HTML. POST with Accept:application/json returns verified:true, signInRequired:true and the supported loginUrl; missing/expired/used tokens return 400 INVALID_VERIFICATION_TOKEN JSON and unexpected failure returns 500 VERIFICATION_FAILED JSON. Successful verification does not create a signed-in session. A separately TXT-verified external website can receive the email at its saved callback; arbitrary supplied return destinations are not accepted. Never poll, log or share a verification URL.
Request, response and error reference
Query and header parameters
[
{
"name": "Accept",
"in": "header",
"required": false,
"schema": {
"type": "string"
},
"description": "Send application/json for the server-to-server verification response; otherwise HTML is returned."
}
]
Request (application/json)
{
"type": "object",
"properties": {
"token": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
},
"program_invite": {
"type": "string"
}
},
"required": [
"token"
],
"additionalProperties": true
}
HTTP 200 response (text/html)
{
"type": "string"
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"verified": {
"const": true
},
"signInRequired": {
"const": true
},
"loginUrl": {
"type": [
"string",
"null"
]
}
},
"required": [
"verified",
"signInRequired",
"loginUrl"
],
"additionalProperties": true
}
Error response formats: text/html or application/json.
Documented failures: 400, 500.
/api/auth/forgot-password
Request account password recovery
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- email: string (required)
- account_type: customer | platform
- storefrontSlug: string
- resetBaseUrl: string
- origin: string
- programInviteToken: string
- Returns
- HTTP 200: message, code.
- Notes
- The response does not disclose whether the email has an account. Send storefrontSlug for store-local recovery: a saved store credential receives a store-only reset. A separately TXT-verified external website uses its saved reset callback, not an arbitrary supplied reset destination. Without store context, shared-account recovery remains separate. Invitation recovery requires account_type and retains its platform destination. Reset delivery is separate from this HTTP success.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"account_type": {
"type": "string",
"enum": [
"customer",
"platform"
]
},
"storefrontSlug": {
"type": "string"
},
"resetBaseUrl": {
"type": "string"
},
"origin": {
"type": "string"
},
"programInviteToken": {
"type": "string"
}
},
"required": [
"email"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/auth/reset-password
Consume a private one-time reset token
- Auth
- Public request; operation-specific verification still applies
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Request fields
- token: string (required)
- newPassword: string (required)
- programInviteToken: string
- Returns
- HTTP 200: message, code.
- Notes
- Aliases resetToken/reset_token and password are accepted. The token is private and one-use. A store reset changes only that store password and invalidates its credential sessions; shared SoundSync credentials and other stores remain unchanged. Shared-account recovery retains its account-session revocation behavior. Invalid or expired tokens do not create a session.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"token": {
"type": "string"
},
"newPassword": {
"type": "string",
"minLength": 8
},
"programInviteToken": {
"type": "string"
}
},
"required": [
"token",
"newPassword"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 500.
/api/auth/logout
Revoke the presented account session
- Auth
- Account Bearer session token
- Scope
- The operation-specific account, workspace, product and ownership checks apply.
- Returns
- HTTP 200: ok.
- Notes
- Revokes the presented account session, not every account session. A failed session deletion returns 503 SESSION_REVOCATION_UNAVAILABLE; it is not a completed sign-out. Retry instead of assuming server revocation from client-side token removal.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 401, 500, 503.
Operation errors: SESSION_REVOCATION_UNAVAILABLE.
/api/auth/me
Read the signed-in account
- Auth
- Account Bearer session token
- Scope
- The signed-in account. Optional workspace discovery requires its current permitted membership or eligible initial setup; every workspace action rechecks its own authorization.
- Request fields
- query developerWorkspace: string. Only the exact value 1 includes developerWorkspace; omitted or other values return account identity only.
- header x-soundsync-workspace-id: string. Optional workspace selection for developerWorkspace=1. Active membership is still required. x-developer-workspace-id is a supported header alias.
- query workspaceId: integer. Optional selector when requesting workspace context. workspace_id is an accepted alias; the workspace header takes precedence.
- Returns
- HTTP 200: user, developerWorkspace.
- Notes
- Returns the signed-in user. With developerWorkspace=1, also returns the current permitted workspace context without creating a workspace, membership or session. An active context has access; an eligible new developer can instead have available:true, initializationRequired:true and no access until the existing authenticated setup initializes their own workspace. Missing/inactive membership or workspace returns HTTP 200 with available:false and reason; it is not an expired-login response. A platform owner can have ownerPortalAvailable:true but no developer workspace. A customer-role account with active team membership can have permitted developer access. Identity alone, a selector or cached context never authorizes another route: the server rechecks current permissions and product scope. Responses use Cache-Control:no-store. Unexpected context failures, including invalid selector parsing, currently return 500 Failed to load session; do not treat every failed context check as invalid credentials.
Request, response and error reference
Query and header parameters
[
{
"name": "developerWorkspace",
"in": "query",
"schema": {
"type": "string",
"enum": [
"1"
]
},
"required": false,
"description": "Only the exact value 1 includes developerWorkspace; omitted or other values return account identity only."
},
{
"name": "x-soundsync-workspace-id",
"in": "header",
"required": false,
"schema": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"description": "Optional workspace selection for developerWorkspace=1. Active membership is still required. x-developer-workspace-id is a supported header alias."
},
{
"name": "workspaceId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": "Optional selector when requesting workspace context. workspace_id is an accepted alias; the workspace header takes precedence."
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"role": {
"type": "string"
},
"is_reseller": {
"type": "boolean"
},
"phone": {
"type": [
"string",
"null"
]
},
"avatarUrl": {
"type": [
"string",
"null"
]
},
"is_admin": {
"type": "boolean"
}
},
"additionalProperties": true
},
"developerWorkspace": {
"oneOf": [
{
"type": "object",
"properties": {
"available": {
"const": true
},
"initializationRequired": {
"const": false
},
"ownerPortalAvailable": {
"type": "boolean"
},
"access": {
"type": "object",
"properties": {
"workspaceId": {
"type": "integer",
"minimum": 1
},
"workspaceOwnerUserId": {
"type": "integer",
"minimum": 1
},
"workspaceDisplayName": {
"type": "string"
},
"membershipId": {
"type": "integer",
"minimum": 1
},
"userId": {
"type": "integer",
"minimum": 1
},
"effectiveDeveloperId": {
"type": "integer",
"minimum": 1
},
"isWorkspaceOwner": {
"type": "boolean"
},
"role": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"productScopeMode": {
"type": "string"
},
"allowedProductIds": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"minimum": 1
}
}
},
"additionalProperties": true
}
},
"required": [
"available",
"initializationRequired",
"ownerPortalAvailable",
"access"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"available": {
"const": true
},
"initializationRequired": {
"const": true
},
"ownerPortalAvailable": {
"type": "boolean"
},
"reason": {
"type": "null"
}
},
"required": [
"available",
"initializationRequired",
"ownerPortalAvailable",
"reason"
],
"additionalProperties": true
},
{
"type": "object",
"properties": {
"available": {
"const": false
},
"initializationRequired": {
"const": false
},
"ownerPortalAvailable": {
"type": "boolean"
},
"reason": {
"type": "string",
"enum": [
"developer_workspace_access_required",
"developer_workspace_not_found",
"developer_team_membership_inactive"
]
}
},
"required": [
"available",
"initializationRequired",
"ownerPortalAvailable",
"reason"
],
"additionalProperties": true
}
],
"description": "Optional read-only workspace discovery. available:true with initializationRequired:true is not an initialized workspace or a permission grant."
}
},
"required": [
"user"
],
"additionalProperties": true
}
Documented failures: 401, 403, 500, 503.
/api/account/profile
Update profile details or request an email change
- Auth
- Account Bearer session token
- Scope
- The signed-in personal account only; not an effective developer workspace or product assignment.
- Request fields
- firstName: string,null
- lastName: string,null
- phone: string,null
- email: string
- avatarUrl: string,null
- Returns
- HTTP 200: message, emailChanged, emailChangeRequested, signInRequired, emailDelivery, user.
- Notes
- Names can be cleared independently. Customer email edits apply immediately to the permitted profile and are not proof of inbox verification. A store-only session updates only that store contact/credential; an email change invalidates old store sessions. Marketing contacts, supported unsent work and current contact references follow the permitted edit. A shared customer session changes the shared customer profile without overwriting saved store overrides; store edits never retarget the shared Stripe billing identity. Platform/developer email changes use the pending verified email-change flow. Issued invoices and sent messages are not rewritten; saved marketing suppressions remain in force.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"email": {
"type": "string",
"format": "email"
},
"avatarUrl": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"emailChanged": {
"type": "boolean"
},
"emailChangeRequested": {
"type": "boolean"
},
"signInRequired": {
"type": "boolean"
},
"emailDelivery": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"role": {
"type": "string"
},
"is_reseller": {
"type": "boolean"
},
"phone": {
"type": [
"string",
"null"
]
},
"avatarUrl": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/account/update-password
Change the password using the current password
- Auth
- Account Bearer session token
- Scope
- The signed-in personal account only; not an effective developer workspace or product assignment.
- Request fields
- currentPassword: string
- oldPassword: string
- newPassword: string (required)
- Returns
- HTTP 200: message, code, signInRequired.
- Notes
- Send currentPassword (or oldPassword) and newPassword. A store-only session changes only its store password and returns signInRequired:true; sign in again to that store. Shared SoundSync passwords and other stores are untouched. Shared-account verification, replacement and other-session revocation remain transactional: a failed revocation rolls the change back, and the recognized current token is retained where present. Passwords must use at least 8 characters and fit within 72 UTF-8 bytes.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"currentPassword": {
"type": "string"
},
"oldPassword": {
"type": "string"
},
"newPassword": {
"type": "string",
"minLength": 8
}
},
"required": [
"newPassword"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"signInRequired": {
"type": "boolean"
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/account/email-change/verify
Verify an email change and return JSON
- Auth
- Public request; operation-specific verification still applies
- Scope
- Private email-change confirmation token; POST confirms the pending change without requiring a sign-in session.
- Request fields
- token: string (required)
- Returns
- HTTP 200: message, email.
- Notes
- The private email token authorizes confirmation without a login session. JSON requests return JSON; browser form submissions return HTML with the same outcome. Reconfirming a completed change succeeds only while that address is still current. Expired, replaced or cancelled links cannot change the address; request a new link from the account.
Request, response and error reference
Request (application/json or application/x-www-form-urlencoded)
{
"type": "object",
"properties": {
"token": {
"type": "string"
}
},
"required": [
"token"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true
}HTTP 200 response (text/html)
{
"type": "string"
}
Error response formats: application/json or text/html.
Documented failures: 400, 404, 409, 410, 500.
/api/account/email-change/verify
Open the email-change verification page
- Auth
- Public request; operation-specific verification still applies
- Scope
- Private email-change token authorizes viewing its confirmation form only; GET does not consume the token or change the address.
- Request fields
- query token: string (required)
- Returns
- HTTP 200: text/html.
- Notes
- Shows a confirmation form without consuming the token or changing the email. GET and HEAD are safe for email scanners. The customer must submit Confirm email change; token validity and email conflicts are checked by POST. Responses are not cached.
Request, response and error reference
Query and header parameters
[
{
"name": "token",
"in": "query",
"schema": {
"type": "string"
},
"required": true,
"description": ""
}
]
No request body fields are read by this operation.
HTTP 200 response (text/html)
{
"type": "string"
}
Documented failures: 400, 500.
Verify the account, then sign in
Ordinary registration returns 202 and requests inbox verification. A valid, previously verified popup setup proof can instead return 200 ACCOUNT_READY without a second verification email. Neither response creates a signed-in session. GET and ordinary POST /api/auth/verify-email consume the private token and return HTML. For a private platform integration, POST with Accept:application/json returns verified:true, signInRequired:true and loginUrl; missing, used or expired proof returns 400 INVALID_VERIFICATION_TOKEN. Follow the supported sign-in continuation separately. A TXT-verified external website uses its saved callback; do not invent or accept arbitrary return destinations, create another account or poll the verification link.
Recover without exposing account existence
Password-reset request responses do not confirm that the address has an account. Send the intended customer/storefront or platform context. Reset tokens and verification links are private, expire under their configured policy and must not be logged or published.
For ordinary registration, check emailSent separately from the 202 email-verification state. Shared customer profile email edits take effect immediately but do not establish inbox ownership; platform/developer email changes use the pending verification flow. Store-only profile edits do not change either shared login or another store. Changing a password requires the current password; reset uses the private reset token instead.
SoundSync
Illustrative password recovery
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/auth/forgot-password" \
-H "Content-Type: application/json" \
--data '{"email":"customer@example.com","account_type":"customer","storefrontSlug":"your-store"}'
Evidence and sensitive responses
These contracts are reviewed against source and synthetic tests, not live requests against customer accounts. Treat account tokens, reset tokens, verification links, authenticator secrets, recovery codes and private profile information as confidential. Provider delivery and account mutations are not exercised by opening this reference.
Branded storefront session handoff
The signed-in customer can POST /api/auth/storefront-bridge/issue with the allowed published storefront origin and optional storefrontSlug. The returned bridgeToken is private, single-use, origin-bound and expires after five minutes. It is not a developer token or a public account lookup.
POST /api/auth/storefront-bridge/redeem exchanges that token at the matching origin for a saved customer session. If both header Origin and body origin are present, they must match. An expired or consumed token returns BRIDGE_TOKEN_INVALID. A later failure can consume the bridge before session creation finishes: obtain a new bridge from the existing signed-in account rather than replaying it. Check that the browser stored the returned session before navigating into the account.
Program invitation verification and legacy login
POST /api/auth/partner-program-verification accepts email and the private programInviteToken to request another account-verification message. The generic success message does not disclose account existence, acceptance or delivery. Invitation terms, identity, expiry, moderation and resend cooldown still apply.
GET /api/auth/hise-login is a legacy compatibility alias, not a JUCE requirement. It shares the normal login limit. New HISE, JUCE and custom clients should use POST /api/auth/login with JSON and finish any MFA challenge there. Do not put passwords in URLs; do not copy old query-based examples into new integrations.
SoundSync
Prepare a private customer handoff
curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/auth/storefront-bridge/issue" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" \
-H "Content-Type: application/json" \
--data '{"origin":"https://store.example","storefrontSlug":"example-store"}'
# Use the actual allowed origin and slug. Keep the returned bridgeToken private.
# Redeem it once at the matching storefront using the documented JSON contract.
SoundSync
Requests and responses
/api/auth/storefront-bridge/issue
Prepare a customer session handoff to a branded storefront
- Auth
- Account Bearer session token
- Scope
- Verified customer account session and an allowed published storefront origin. Not developer workspace access.
- Request fields
- origin: string (required)
- storefrontSlug: string
- Returns
- HTTP 200: bridgeToken, expiresAt, origin, storefrontSlug.
- Notes
- First-party customer sign-in handoff. Issues a private, origin-bound, single-use token with a five-minute lifetime. Storefront slug aliases are supported. This creates a bridge record; it is not a zero-write readiness probe. Never publish the token or send it to another origin.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"origin": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
}
},
"required": [
"origin"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"bridgeToken": {
"type": "string"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"origin": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: CUSTOMER_SESSION_REQUIRED, STOREFRONT_ORIGIN_NOT_ALLOWED.
/api/auth/storefront-bridge/redeem
Exchange a private handoff token for a storefront customer session
- Auth
- Public request; operation-specific verification still applies
- Scope
- Private bridge token, its allowed origin and storefront. No account JWT is required for the exchange itself.
- Request fields
- bridgeToken: string (required)
- origin: string (required)
- storefrontSlug: string
- Returns
- HTTP 200: token, accessToken, customerToken, user, storefront.
- Notes
- Consumes the token atomically, checks the customer account and records a 30-day customer session. If an Origin header and body origin are both present, they must match. Expired or consumed tokens return 401. The exchange is not whole-workflow atomic: a later failure can consume the bridge without returning a session. Obtain a new bridge through the existing signed-in account instead of replaying it. An HTTP 200 does not prove the browser successfully stored the session.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"bridgeToken": {
"type": "string"
},
"origin": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
}
},
"required": [
"bridgeToken",
"origin"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"token": {
"type": "string"
},
"accessToken": {
"type": "string"
},
"customerToken": {
"type": "string"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email"
},
"first_name": {
"type": [
"string",
"null"
]
},
"last_name": {
"type": [
"string",
"null"
]
},
"firstName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"role": {
"const": "customer"
}
},
"additionalProperties": true
},
"storefront": {
"type": "object",
"properties": {
"developerId": {
"type": "integer",
"minimum": 1
},
"storefrontId": {
"type": [
"integer",
"null"
]
},
"slug": {
"type": "string"
},
"origin": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: BRIDGE_TOKEN_REQUIRED, BRIDGE_TOKEN_INVALID, STOREFRONT_BRIDGE_ORIGIN_MISMATCH, STOREFRONT_ORIGIN_NOT_ALLOWED, CUSTOMER_SESSION_UNAVAILABLE.
/api/auth/partner-program-verification
Request another verification email for an eligible program invitation
- Auth
- Public request; operation-specific verification still applies
- Scope
- Public invitation recovery; the private invitation must match an eligible unverified recipient account.
- Request fields
- email: string (required)
- programInviteToken: string (required)
- Returns
- HTTP 200: message.
- Notes
- Rate-limited by IP and normalized email. Returns the same generic 200 message whether or not mail is queued; it does not disclose account existence or prove delivery. Checks invitation expiry, current terms, recipient identity, account status and cooldown. Does not accept an agreement, create earnings or sign in the recipient.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"programInviteToken": {
"type": "string"
}
},
"required": [
"email",
"programInviteToken"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 429, 500.
/api/auth/hise-login
Legacy GET account login compatibility route
- Auth
- Public request; operation-specific verification still applies
- Scope
- Only the matching verified account. Legacy first-party compatibility, not a HISE requirement or recommended new integration.
- Request fields
- query email: string
- query password: string
- query role: string
- query format: string
- query hise_text: string
- Returns
- HTTP 200: token, accessToken, customerToken, user, twoFactorRequired, twoFactorToken, code, message.
- Notes
- Use POST /api/auth/login with a JSON body for all new clients, including JUCE. This alias shares the normal login rate-limit bucket. Legacy account/email/password query aliases are accepted, but URLs can expose credentials through logging and history; never put them in examples, screenshots or support reports. hise_text or format=hise_text returns the legacy text transport after successful sign-in. MFA challenges must be completed through the supported POST flow. Route presence does not imply that JUCE requires HISE authentication.
Request, response and error reference
Legacy operation. Use the current scoped APIs for new integrations.
Query and header parameters
[
{
"name": "email",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "password",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "role",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "format",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "hise_text",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
]
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"token": {
"type": "string"
},
"user": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"twoFactorRequired": {
"type": "boolean"
},
"twoFactorToken": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (text/plain)
{
"type": "string"
}
Documented failures: 400, 401, 403, 429, 500.
Choose store or shared-account recovery
A storefront email/password override is valid only with that storefront context. Send storefrontSlug when requesting its password reset. Store resets are one-use, expire after 60 minutes and leave shared-account credentials unchanged. Email or password changes supersede earlier store reset links.
Shared-account customer profile email edits take effect immediately; they do not prove inbox ownership. Platform/developer email changes use the separate verified pending-change procedure. A store profile edit remains local, and a store password change requires signing in again. Store credentials retain the linked account two-factor challenge; they do not disable or replace global two-factor settings.
SoundSync suspension and store restrictions
A SoundSync-wide customer-account suspension blocks customer library and download authorization, including requests made with an existing signed-in session. A restriction imposed by one store remains scoped to that store; unrelated stores remain available unless the SoundSync account is also suspended.
Suspension does not delete purchase history or create a refund. Contact SoundSync support about a platform restriction and the developer about a store restriction. A previously issued storage link can remain usable until it expires; already downloaded files cannot be recalled by an account restriction.
Store sessions have a deliberate boundary
POST /api/auth/login accepts storefrontSlug for store sign-in. For a saved store credential, the response user includes storefrontSession:true and storefrontDeveloperId. Keep that context through any two-factor continuation. The token is scoped to that store library and contact/password settings, not shared payment or account-security authority. Managed checkout, subscription billing and serial claims retain their shared-account sign-in requirement. Product-scoped customer-token activation can accept store proof only for that same developer, with the normal ownership/device checks; it is never cross-store or developer authority.
Use the shared SoundSync sign-in for global security settings, cross-store actions and other shared-account operations. Checkout prompts use shared sign-in and shared password recovery, even on a branded store domain; a store-assigned password cannot authorize shared billing. Generated native packages keep their documented shared-customer sign-in flow; changing a store password does not change the shared password used there. A scope mismatch returns 403 STOREFRONT_SESSION_SCOPE. Invalidated store credentials require sign-in; session verification failure returns 503 rather than granting access.
SoundSync
Private reseller invitation verification
/api/auth/reseller-verification
Request verification mail for a private pending reseller invitation
- Auth
- Public request; operation-specific verification still applies
- Scope
- Private intended-recipient invitation proof, active pending invitation/account and resend limits.
- Request fields
- email: string (required)
- partnerInviteToken: string (required)
- Returns
- HTTP 200: message.
- Notes
- Generic success does not confirm account existence, invitation acceptance or email delivery. Keep invitation tokens private; repeated requests remain rate/cooldown limited.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"partnerInviteToken": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"email",
"partnerInviteToken"
]
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 500, 503.
Select the login family without granting a role
When a separate customer account and developer account share an email, send accountType:platform (or the existing developer role hint) for team sign-in, and accountType:customer for customer sign-in. The account_type alias is supported. This selects which login records are considered; it does not assign an owner, administrator or other role. Password, two-factor, verification and invitation acceptance checks still apply.
Check the workspace, not only the sign-in
GET /api/auth/me normally returns account identity. Add developerWorkspace=1 to request read-only workspace discovery. The optional developerWorkspace object distinguishes active access, an eligible first-time setup and an unavailable workspace. This request does not create a workspace, accept an invitation or grant permissions.
With available:true and initializationRequired:false, use access for the selected workspace identity, role, permissions and product scope. With available:true and initializationRequired:true, an eligible new developer still needs the existing authenticated setup to initialize their own workspace; access is not returned yet. With available:false, inspect reason instead of treating the result as an expired password or failed connection.
The supported unavailable reasons are developer_workspace_access_required, developer_workspace_not_found and developer_team_membership_inactive. ownerPortalAvailable describes access to the separate platform-owner portal; it does not grant a developer workspace. An invited account can have an ordinary customer role and still have active team access. Every later API request rechecks current membership, permissions and product scope.
SoundSync
Read workspace context without changing it
curl --fail-with-body -sS "$SOUNDSYNC_API_BASE/api/auth/me?developerWorkspace=1" \
-H "Authorization: Bearer $ACCOUNT_TOKEN" \
-H "x-soundsync-workspace-id: $WORKSPACE_ID"
Keep session discovery private
Omit the workspace header when no explicit selection is needed. x-developer-workspace-id and workspaceId/workspace_id are supported selectors; a header takes precedence. Select only a workspace the account is permitted to use. The response is no-store; do not publish the account token, private profile or access context.
Without developerWorkspace=1, developerWorkspace is omitted. A well-formed unavailable context returns HTTP 200 with available:false. Invalid selector parsing or an unexpected lookup failure currently returns 500 Failed to load session; correct the selector or retry after recovery instead of repeatedly signing in. No response from this read accepts an invitation or grants permission.
Shared account aliases are not store-local sign-in
Prefer /api/account paths for maintained account clients. The older /api/security, /api/profile and /api/update-password paths share handlers, but the store-session allowlist does not accept those root URLs. A store-only session can use its supported canonical security/profile/password path without gaining shared-account authority. It cannot use either mount for shared two-factor setup or saved-card management.
The email-change aliases use their private confirmation token, not a store password. GET shows the confirmation form without changing the address; POST confirms it. Do not confuse this with /api/auth/verify-email, whose account-verification token is consumed by GET or POST.
Reload security details after an unavailable lookup
A failed security/session-count lookup is an error, not confirmation of zero saved sessions. Retry after the service recovers. A successful count describes stored sessions; it is not an online-device monitor. Store-only security responses intentionally omit shared security/session details.
A successful security change and its following status refresh are separate results. If the change succeeds but the refresh fails, retain the success and any recovery codes shown once, display unavailable status, and retry only the status lookup. Do not repeat a code rotation or disable request just to refresh the display.
After a store-local profile or password edit, inspect signInRequired. A changed store email or password can require a fresh sign-in to that store, without changing the shared SoundSync login or unrelated storefronts. Do not treat an HTTP 200 edit alone as permission to keep using an invalidated store session.
SoundSync
Account compatibility operation map
| Method | Compatibility path | Contract or result |
|---|---|---|
| GET | /api/security | GET /api/account/security. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| PUT | /api/profile | PUT /api/account/profile. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| POST | /api/update-password | POST /api/account/update-password. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| POST | /api/2fa/setup | POST /api/account/2fa/setup. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| POST | /api/2fa/enable | POST /api/account/2fa/enable. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| POST | /api/2fa/disable | POST /api/account/2fa/disable. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| GET | /api/payment-method | GET /api/account/payment-method. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| POST | /api/payment-method | POST /api/account/payment-method. The older root path requires shared SoundSync account sign-in. A store-only credential session is rejected before this handler, including for profile, password and security reads that have a supported store-local canonical path. |
| GET | /api/email-change/verify | GET /api/account/email-change/verify. The private email-change proof has the same confirmation semantics at both mounts. GET displays a form without consuming it; POST confirms the change. |
| POST | /api/email-change/verify | POST /api/account/email-change/verify. The private email-change proof has the same confirmation semantics at both mounts. GET displays a form without consuming it; POST confirms the change. |
SoundSync
Historical personal saved-card operations
/api/account/payment-method
Read the signed-in shared account's saved-card preview
- Auth
- Account Bearer session token
- Scope
- Shared SoundSync account session; reads only that account user's stored card preview, not a selected workspace or store-only profile.
- Returns
- HTTP 200: brand, last4, exp_month, exp_year.
- Notes
- Historical first-party saved-card endpoint for the signed-in shared SoundSync account, not the selected developer workspace. Uses the configured legacy Stripe client; there is no request environment selector. Store-only sessions are denied with 403 STOREFRONT_SESSION_SCOPE before Stripe or card queries. This does not create a checkout, tax quote, payout destination, Connect onboarding, transfer or automatic-execution change. Prefer the current developer Billing API for workspace billing and managed checkout for customer purchases. No saved method returns 404 No payment method found, not a 200 empty card. Returns only brand, last4, exp_month and exp_year when available, never the full card number or security code. This read contacts Stripe but does not attach a card.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"brand": {
"type": "string"
},
"last4": {
"type": "string"
},
"exp_month": {
"type": "integer"
},
"exp_year": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 401, 403, 404, 500, 503.
Operation errors: STOREFRONT_SESSION_SCOPE.
/api/account/payment-method
Save the signed-in shared account's legacy Stripe payment method
- Auth
- Account Bearer session token
- Scope
- Shared SoundSync account session; changes only the signed-in account user's legacy Stripe customer/default payment method.
- Request fields
- payment_method_id: string (required)
- Returns
- HTTP 200: message, brand, last4, exp_month, exp_year.
- Notes
- Historical first-party saved-card endpoint for the signed-in shared SoundSync account, not the selected developer workspace. Uses the configured legacy Stripe client; there is no request environment selector. Store-only sessions are denied with 403 STOREFRONT_SESSION_SCOPE before Stripe or card queries. This does not create a checkout, tax quote, payout destination, Connect onboarding, transfer or automatic-execution change. Prefer the current developer Billing API for workspace billing and managed checkout for customer purchases. Requires a Stripe payment-method identifier, not raw card data. Can create a Stripe customer and save its ID, attach the supplied method, set the default invoice method and persist its identifier. These provider/database writes are not one atomic transaction. On an uncertain failure, inspect the saved method before retrying. A successful save does not itself collect a charge or pay a payout.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"payment_method_id": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"payment_method_id"
]
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"brand": {
"type": "string"
},
"last4": {
"type": "string"
},
"exp_month": {
"type": "integer"
},
"exp_year": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 500, 503.
Operation errors: STOREFRONT_SESSION_SCOPE.
A saved card is not a checkout or payout setup
These historical personal endpoints use the signed-in account, not a workspace selector. They do not replace the developer Billing API, customer managed checkout or Stripe Connect payout setup. A read can return 404 when no method is saved. A write can create/attach provider records and set a default; it is not an atomic operation across Stripe and the database. Reconcile an uncertain result before retrying. Store-only credentials cannot read or change this shared card.
SoundSync
