Users#

Manage user profiles, per-user settings, and user lifecycle operations.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/users#

List users in an organization with pagination and name search.

bash

GET /v1/users?page_index=0&page_size=25&organization_id=org_123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`string`	—	Column name to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.

Response#

Returns { items, totalCount, facets } with paginated results.

Underlying SDK method: bw.users.list(params)

POST /v1/users#

Create a new user record during sign-up.

bash

POST /v1/users
Authorization: Bearer {token}
Content-Type: application/json

{
  "user_id": "user_abc123",
  "email": "user@example.com"
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier (from auth provider).
email	`string`	Required	User email address.
name	`string \| null`	—	User display name (max 255 characters).
jobRole	`string \| null`	—	User job role (max 100 characters).

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.create(params)

GET /v1/users/:id#

Retrieve a single user by ID.

bash

GET /v1/users/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	User identifier.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users({ id })

PATCH /v1/users/:id#

Update a user's profile information. Updatable fields: name (display name), email, jobRole (e.g. 'Head of Marketing'), avatarKey (storage key, null to remove). Only include the fields you want to change.

bash

PATCH /v1/users/:id
Authorization: Bearer {token}
Content-Type: application/json

{
  "user_id": "user_abc123"
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier to update.
name	`string`	—	Updated display name (1-255 characters).
email	`string`	—	Updated email address.
jobRole	`string \| null`	—	Updated job role (max 100 characters).
avatarKey	`string \| null`	—	Storage key for the user avatar image. Set to null to remove.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.update(params)

POST /v1/users/:id/avatar/upload-url#

Request a presigned URL for uploading a user avatar image. The client uploads the file directly using the returned URL, then calls PATCH /users/:id with the avatarKey.

bash

POST /v1/users/:id/avatar/upload-url
Authorization: Bearer {token}
Content-Type: application/json

{
  "user_id": "user_abc123",
  "content_length": "...",
  "content_type": "..."
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier requesting an avatar upload URL.
contentLength	`integer`	Required	Size of the file in bytes.
contentType	`'image/jpeg' \| 'image/png' \| 'image/webp' \| 'image/gif'`	Required	MIME type of the file.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.requestAvatarUpload(params)

POST /v1/users/:id/change-email#

Request a change to the user's email address.

bash

POST /v1/users/:id/change-email
Authorization: Bearer {token}
Content-Type: application/json

{
  "user_id": "user_abc123",
  "new_email": "..."
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier requesting the email change.
newEmail	`string`	Required	The new email address to change to.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.changeEmail(params)

POST /v1/users/:id/request-deletion#

Request an account deletion confirmation email after verifying ownership safeguards.

bash

POST /v1/users/:id/request-deletion
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	User identifier requesting account deletion.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.requestDeletion(params)

POST /v1/users/:id/confirm-deletion#

Validate an account deletion token and re-check ownership safeguards before final deletion.

bash

POST /v1/users/:id/confirm-deletion
Authorization: Bearer {token}
Content-Type: application/json

{
  "token": "..."
}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	User identifier confirming account deletion.
token	`string (UUID)`	Required	Deletion confirmation token from the email link.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.confirmDeletion(params)

DELETE /v1/users/:id#

Delete a user account using an optional email confirmation token, revoke access, remove memberships, and clear saved profile details.

bash

DELETE /v1/users/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	User identifier to delete.
token	`string (UUID)`	—	Optional deletion confirmation token from the email link.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.delete(params)

GET /v1/users/:id/settings#

Retrieve a user's personal settings.

bash

GET /v1/users/:id/settings?user_id=user_abc123
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier to fetch settings for.

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.settings(params)

PATCH /v1/users/:id/settings#

Create or update a user's settings, including switching the active organization and managing UI preferences.

bash

PATCH /v1/users/:id/settings
Authorization: Bearer {token}
Content-Type: application/json

{
  "user_id": "user_abc123"
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier to update settings for.
activeOrganizationId	`string (UUID)`	—	Organization to set as the active workspace.
preferences	`object`	—	User UI preferences (shallow-merged into existing).

Response#

Returns { data } with the result.

Underlying SDK method: bw.users.settings.update(params)