# 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](/workspaces/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](/users/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.

```typescript
// Server-side: the user's membership of a workspace
await bb.users.invite(workspaceId, 'teammate@example.com', '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' });
```

> **Note:**
  `bb.users.invite()` respects seat limits. Check
  [`useSeatStatus()`](/workspaces/managing-members) 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](/users/user-attributes)          |
| Segment people for a campaign      | [Audience and lists](/users/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](/reference/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](/users/user-attributes) — custom fields on a user.
- [Audience and lists](/users/audience-and-lists) — contacts, tags, and import.
- [Managing members](/workspaces/managing-members) — roles and seats in a workspace.