Overview

Control who can see and do what with role-based access control.

Every workspace member has a role. Use WhenPermission to show or hide UI, and usePermissions() when you need to check permissions in code.

import { Permission, WhenPermission } from '@buildbase/sdk/react';

function Sidebar() {
  return (
    <nav>
      <WhenPermission permission={Permission.WORKSPACE_MEMBERS_INVITE}>
        <a href="/team">Team</a>
      </WhenPermission>
      <WhenPermission permission={Permission.WORKSPACE_BILLING_MANAGE}>
        <a href="/billing">Billing</a>
      </WhenPermission>
    </nav>
  );
}

Default roles

Three roles ship with default permission sets:

Role	Default permissions
`owner`	Full access — always has all permissions
`admin`	All workspace permissions except workspace deletion (owner-only)
`member`	View settings, members, features, billing, and usage
`viewer`	View settings and members

Warning

The editor role is assignable (e.g. addUser(workspaceId, email, 'editor')) but has no entry in the default permission maps — an editor resolves to zero permissions until you configure custom permissions for the role, via defaultPermissions on SaaSOSProvider or the workspace permission matrix.

Custom roles can be defined in the BuildBase dashboard.

Components

Component	What it checks
`WhenPermission`	Does the user have a specific permission?
`WhenRoles`	Does the user have one of these org-level roles?
`WhenWorkspaceRoles`	Does the user have one of these workspace roles?

import { WhenWorkspaceRoles } from '@buildbase/sdk/react';

<WhenWorkspaceRoles roles={['owner', 'admin']}>
  <button onClick={() => openWorkspaceSettings()}>Settings</button>
</WhenWorkspaceRoles>;

usePermissions()

For imperative permission checks:

import { Permission, usePermissions } from '@buildbase/sdk/react';

function BillingPage() {
  const { can, isOwner, role } = usePermissions();

  if (!can(Permission.WORKSPACE_BILLING_MANAGE)) {
    return <p>No access to billing.</p>;
  }

  return <BillingSettings />;
}

Return	Type	Description
`can(permission)`	`function`	Check if user has a permission
`permissions`	`Set`	Full set of resolved permissions
`isOwner`	`boolean`	Whether user owns the workspace
`role`	`string`	User's role in the workspace

Custom permissions

Add app-specific permissions via SaaSOSProvider:

<SaaSOSProvider
  defaultPermissions={{
    admin: ['app:analytics:view', 'app:reports:export'],
    editor: ['app:analytics:view'],
  }}
>

Then check them: can('app:reports:export').

Next Steps

Checking Permissions — Permission constants and patterns.
Conditional Rendering — WhenPermission, WhenRoles, WhenWorkspaceRoles.