Skip to content
BuildBase

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>
  );
}
ReturnTypeDescription
memberCountnumberCurrent members. Pending invitations also hold seats; the members screen counts them
includedSeatsnumberSeats in the plan
availableSeatsnumberRemaining seats (Infinity if unlimited)
canInvitebooleanWhether invites are allowed
inviteBlockReason'seat_limit_reached' | 'settings_user_limit_reached' | 'no_subscription' | nullMachine-readable code for why invites are blocked, or null if allowed
inviteBlockMessageKeystring | nulli18n 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

ActionPermission
Invite a memberWORKSPACE_MEMBERS_INVITE
Remove a memberWORKSPACE_MEMBERS_REMOVE
LeaveNone: being a member is enough
Change a roleWORKSPACE_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:

StatuscodeWhenWhat to do
409WORKSPACE_OWNER_CANNOT_LEAVEThe workspace's owner, the person who created it, tried to leave. Ownership cannot be handed to another memberDelete the workspace instead
400noneSomeone else tried to remove the owner (Cannot remove the workspace creator.)The owner stays a member while the workspace exists
400noneThe last admin would leave or be removed (Cannot remove the last admin. Promote another member to admin first.)Make another member an admin first
409PAYER_STILL_PAYSThe person pays for the workspace's subscription with their own card, and is leaving or being removedMove 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