Managing Members
Invite members, assign roles, and track seat usage.
Use the built-in members screen to manage workspace membership. One call handles invites, roles, seat tracking, and permissions automatically.
import { useSaaSAuth } from '@buildbase/sdk/react';
function TeamButton() {
const { openWorkspaceSettings } = useSaaSAuth();
return (
<button onClick={() => openWorkspaceSettings('users')}>Manage Team</button>
);
}The members screen includes:
- Invite members by email with role selection - the address need not have an account yet, see Invitations
- Pending invitations under the form, with resend and revoke
- View all members with their roles
- Change member roles
- Remove members
- Seat usage bar (when seat pricing is enabled)
- Permission-gated - only users with the right permissions see management controls
Note
With @buildbase/sdk
0.0.71
or later on a server from
release 22
, the members screen's invite form sends an invitation to any
address, account or not, and lists it as pending until it is answered. Before
that it added an existing account at once. addUser is unchanged.
Checking seat availability
Use useSeatStatus() to show seat info in your UI:
import { useSeatStatus } from '@buildbase/sdk/react';
function SeatBadge({ workspace }) {
const { memberCount, includedSeats, canInvite } = useSeatStatus(workspace);
return (
<p>
{memberCount} of {includedSeats} seats used
{!canInvite && ' — seat limit reached'}
</p>
);
}| Return | Type | Description |
|---|---|---|
memberCount | number | Current members. Pending invitations also hold seats; the members screen counts them |
includedSeats | number | Seats in the plan |
availableSeats | number | Remaining seats (Infinity if unlimited) |
canInvite | boolean | Whether invites are allowed |
inviteBlockReason | 'seat_limit_reached' | 'settings_user_limit_reached' | 'no_subscription' | null | Machine-readable code for why invites are blocked, or null if allowed |
inviteBlockMessageKey | string | null | i18n key for the human-readable block message - resolve with t(key, inviteBlockMessageValues) |
Programmatic access
If you need to manage members from code (e.g., onboarding flows), use useSaaSWorkspaces():
import { useSaaSWorkspaces } from '@buildbase/sdk/react';
const { addUser, inviteMember, removeUser, updateUser } = useSaaSWorkspaces();
// Invite during onboarding: the address need not have an account yet
await inviteMember(workspaceId, '[email protected]', 'editor');
// Add an account that already exists, at once (404 when it does not)
await addUser(workspaceId, '[email protected]', 'editor');Who cannot be removed
Two members can't be removed, whoever asks: the person who created the workspace, and its last admin. That way a workspace always has someone who can run it. Removing either is refused with 400. Turning invitations off doesn't stop an admin removing anyone else. It does stop new people being added, and it stops changes to members' roles too.
A role change is checked like an add. If the new role takes a seat and the plan has no room, the change is refused, just as an add at the limit would be. And in a workspace a company runs through single sign-on, someone from outside the company can only hold a role the company allows them.
Required permissions
| Action | Permission |
|---|---|
| Invite a member | WORKSPACE_MEMBERS_INVITE |
| Remove a member | WORKSPACE_MEMBERS_REMOVE |
| Leave | None: being a member is enough |
| Change a role | WORKSPACE_MEMBERS_ROLE_CHANGE |
When the app sets canInviteMembers: 'admin-only', inviting and adding a member also need the caller to be the workspace's owner or one of its admins; anyone else gets a 403, and their permissions/me leaves out WORKSPACE_MEMBERS_INVITE. See Invitations.
Nobody hands out more than they hold. The workspace's owner (the person who created it) and its admins can give any role. Anyone else holding one of these permissions can give only roles whose permissions they hold themselves, never admin, cannot change their own role, and cannot change the role of a member who holds something they do not. The same goes for editing a workspace's role permissions with WORKSPACE_SETTINGS_EDIT: below admin, you cannot change your own role's permissions or grant a role anything you lack. A refusal is a 403 with a message that says why.
The owner's role is never changed through the API, by an admin or by the owner: the owner holds every permission whatever their role says. That request answers 409 with code: 'WORKSPACE_OWNER_ROLE_FIXED', as removing the owner is refused.
Leaving a workspace
Any member can leave a workspace on their own: they remove themselves with their own user id, and no permission is needed beyond being a member. Removing anyone else still needs WORKSPACE_MEMBERS_REMOVE. Leaving does everything a removal does: the seat is freed, what the workspace's plan granted them ends, and workspace.member_removed is sent with the leaver as actorId.
import { useSaaSAuth, useSaaSWorkspaces } from '@buildbase/sdk/react';
function LeaveWorkspaceButton({ workspaceId }: { workspaceId: string }) {
const { user } = useSaaSAuth();
const { removeUser } = useSaaSWorkspaces();
if (!user) return null;
return (
<button type="button" onClick={() => removeUser(workspaceId, user.id)}>
Leave workspace
</button>
);
}Over the API it is DELETE /api/v1/public/workspaces/:workspaceId/users/:userId with the caller's own id. These refusals apply to leaving and to removing:
| Status | code | When | What to do |
|---|---|---|---|
409 | WORKSPACE_OWNER_CANNOT_LEAVE | The workspace's owner, the person who created it, tried to leave. Ownership cannot be handed to another member | Delete the workspace instead |
400 | none | Someone else tried to remove the owner (Cannot remove the workspace creator.) | The owner stays a member while the workspace exists |
400 | none | The last admin would leave or be removed (Cannot remove the last admin. Promote another member to admin first.) | Make another member an admin first |
409 | PAYER_STILL_PAYS | The person pays for the workspace's subscription with their own card, and is leaving or being removed | Move billing to another member, or back to the workspace, with transfer-payer, or cancel the subscription |
A PAYER_STILL_PAYS refusal carries workspaceId and subscriptionId beside code and message. It applies only when a person pays: a workspace that pays for itself, or one another workspace pays for, lets anyone leave. To move billing, someone with the workspace's billing-manage permission calls POST /api/v1/public/workspaces/:workspaceId/subscription/transfer-payer naming the new payer: themselves ({ type: 'user', id }, a person pays only as themselves) or the workspace ({ type: 'workspace', id: workspaceId }). It opens a checkout on the new payer's card that starts when the current period ends, so nothing is charged twice; once it completes, the old payer can leave.
Three removals are never refused, and leave the subscription where it is: Directory Sync taking someone out, a company group no longer giving them the workspace, and deleting their account. After one of those the subscription stays billed to the person who paid until billing moves or it is cancelled, so check who pays for your workspaces.
Next Steps
- Invitations - Reach people who have no account yet.
- Mode and limits - Member caps, default role and who may invite, set in the console.
- Settings Screens - All pre-built screens.