API reference

Accounts and Recovery API

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

Start with getting started Explore API docs

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

Account lifecycle operations

POST /api/auth/register

Create an account and request email verification

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
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
Returns: HTTP 202: ok, code, status, emailVerificationRequired, emailSent, message, user.
Notes: Registration creates an unverified account, not 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.

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

POST /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. A storefront context selects customer recovery; invitation recovery requires account_type. 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.

POST /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 successful reset revokes sessions. 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.

POST /api/auth/logout

Revoke the presented account session

Auth: Account Bearer JWT
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.

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: 400, 500.

GET /api/auth/me

Read the signed-in account

Auth: Account Bearer JWT
Scope: The operation-specific account, workspace, product and ownership checks apply.
Returns: HTTP 200: user.
Notes: Returns the current account, not a customer list or developer workspace authorization.

Request, response and error reference

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"
          ]
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 500.

PUT /api/account/profile

Update profile details or request an email change

Auth: Account Bearer JWT
Scope: The operation-specific account, workspace, product and ownership checks apply.
Request fields: firstName: string,null
lastName: string,null
phone: string,null
email: string
avatarUrl: string,null
Returns: HTTP 200: message, emailChangeRequested, emailDelivery, user.
Notes: Names can be cleared independently. An email change requires verification; this response is not proof that the email changed. first_name, last_name and avatar_url aliases are accepted. Issued invoices and sent messages are not rewritten.

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

POST /api/account/update-password

Change the password using the current password

Auth: Account Bearer JWT
Scope: The operation-specific account, workspace, product and ownership checks apply.
Request fields: currentPassword: string
oldPassword: string
newPassword: string (required)
Returns: HTTP 200: message, code.
Notes: Send currentPassword (or oldPassword) and newPassword. Other saved sessions are revoked; the current saved session is retained where present.

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"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 500.

POST /api/account/email-change/verify

Verify an email change and return JSON

Auth: Public request; operation-specific verification still applies
Scope: The operation-specific account, workspace, product and ownership checks apply.
Request fields: token: string (required)
Returns: HTTP 200: message, email.

Request, response and error reference

Request (application/json)

{
  "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
}

Documented failures: 400, 500.

GET /api/account/email-change/verify

Open the email-change verification page

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)
Returns: HTTP 200: text/html.
Notes: Browser verification page. The POST form returns JSON instead.

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.

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.

Registration returns 202 and an email-verification state, not a logged-in session. Check emailSent separately. An email/profile change is not verified until the supported verification step succeeds. Changing a password requires the current password; reset uses the private reset token instead.

SoundSync

Illustrative password recovery

Request a customer reset for your storefront

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.