Overview

Three separate identity concepts - workspace members, app users, and audience contacts - and when each applies.

BuildBase keeps three different ideas of "a person", and most confusion here comes from treating them as one. They live in separate collections and are managed by separate APIs.

Concept	What it is	Managed from
Workspace member	A user's membership of one workspace, carrying a role	Managing members
User	The account itself — credentials, profile, devices, sessions	The console, and `bb.users` server-side
Audience contact	A marketing record. May have no account at all	Audience and lists

A person can be all three, and the records stay distinct. Deleting an audience contact does not delete the user account, and removing someone from a workspace does not delete either.

// Server-side: the user's membership of a workspace
await bb.users.invite(workspaceId, '[email protected]', 'editor');
await bb.users.updateRole(workspaceId, userId, 'admin');
await bb.users.remove(workspaceId, userId);

// The signed-in user's own profile
const me = await bb.users.getProfile();
await bb.users.updateProfile({ name: 'Alice Chen' });

Before you start

bb.users.invite() respects seat limits. Check useSeatStatus() before offering an invite in your UI, or handle the rejection.

Which API to reach for

You want to	Use
Invite or remove a teammate	`bb.users.*`, or `useSaaSWorkspaces()` client-side
Read or edit the signed-in profile	`bb.users.getProfile()` / `updateProfile()`
Store custom fields on a user	User attributes
Segment people for a campaign	Audience and lists
Administer any user in the org	The console, or `/api/users` — see below

bb.users is deliberately narrow: it covers the operations an application performs on its own behalf. Org-wide administration is a console job, exposed over the admin API rather than the SDK.

Administering users over the API

/api/users is the console's own surface. It is broader than the SDK and correspondingly more dangerous, so treat it as an admin tool.

Method	Path	Purpose
`GET`	`/api/users`	List users, paginated
`GET`	`/api/users/:id`	One user
`PATCH`	`/api/users/:id`	Update a user
`PATCH`	`/api/users/:id/block`	Block — the user cannot sign in
`PATCH`	`/api/users/:id/unblock`	Restore access
`PATCH`	`/api/users/:id/change-role`	Change the org-level role
`PATCH`	`/api/users/:id/tags`	Replace the user's tags
`GET`	`/api/users/:id/workspaces`	Workspaces this user belongs to
`GET`	`/api/users/:id/devices`	Known devices
`GET`	`/api/users/:id/sessions`	Active sessions
`GET`	`/api/users/:id/activities`	Activity history
`GET`	`/api/users/:id/features`	Resolved user feature flags
`GET`	`/api/users/:id/emails`	Email sent to this user
`DELETE`	`/api/users/:id`	Delete the user

Sessions and devices can be revoked individually with DELETE /api/users/:id/sessions/:sessionRef and DELETE /api/users/:id/devices/:deviceId — useful for a support flow that signs one device out without ending every session.

Blocking is the reversible option and deletion is not. Prefer PATCH /:id/block for abuse handling.

Next Steps

User attributes — custom fields on a user.
Audience and lists — contacts, tags, and import.
Managing members — roles and seats in a workspace.