Decide who can do what, per workspace.
Every workspace member has a role, and each role resolves to a set of permissions that both your UI and the BuildBase API check. You add your own permission strings next to the built-in ones, and a workspace can change what a role may do without a deploy.
Your app is an organization in BuildBase. Your users sign in and work inside workspaces - one per team or customer.
You set up
In the console and the SDK
- Which parts of your app each role can use
- Permissions of your own, like exporting reports
- Default roles, which a workspace can adjust for itself
Your users get
Inside their workspace
- Owners and admins who decide what each teammate can do
- Only the buttons and pages their role allows
- The same rules enforced by the API, not only hidden in the UI
Access control your API agrees with
The same role map drives the components in your UI and the checks on the BuildBase API, so a hidden button is not the only thing in the way.
Show What Each Role Allows
Wrap part of your app and it appears only for the roles that should see it, with a fallback for everyone else.
Check in Code
Ask whether the current user may do something before you do it, from your front end or your server.
Your Own Permissions
Add permissions for your own features, like exporting reports, and check them the same way as the built-in ones.
Enforced by the API
A viewer who calls the API directly still cannot invite people, change roles, manage billing or spend credits.
Adjust per Workspace
You set the default roles. A workspace can loosen or tighten them for itself without changing them for anyone else.
Roles for API Keys
API keys get their own roles, and a key can never do more than the person who created it.
Gate the UI, then check on the server
WhenPermission and usePermissions() hide what a role cannot use. bb.permissions.check() gives your own API routes the same answer.
import {
usePermissions,
useSaaSAuth,
useSeatStatus,
WhenPermission,
WhenWorkspaceRoles,
Permission,
} from '@buildbase/sdk/react';
function TeamPage({ workspace }) {
const { can } = usePermissions();
const { openWorkspaceSettings } = useSaaSAuth();
const {
memberCount, includedSeats, availableSeats,
isAtMax, canInvite, inviteBlockReason,
} = useSeatStatus(workspace);
return (
<>
<p>{memberCount} of {includedSeats} seats used</p>
<WhenPermission permission={Permission.WORKSPACE_MEMBERS_INVITE}>
<button disabled={!canInvite}>
{canInvite ? 'Invite Member' : inviteBlockReason}
</button>
</WhenPermission>
<WhenWorkspaceRoles roles={['owner', 'admin']}>
<button onClick={() => openWorkspaceSettings('permissions')}>
Manage Permissions
</button>
</WhenWorkspaceRoles>
{can(Permission.WORKSPACE_BILLING_MANAGE) && <BillingLink />}
</>
);
}import BuildBase, { Permission } from '@buildbase/sdk';
import { cookies } from 'next/headers';
const bb = BuildBase({
serverUrl: process.env.BUILDBASE_SERVER_URL!,
orgId: process.env.BUILDBASE_ORG_ID!,
getSessionId: async () =>
(await cookies()).get('bb-session-id')?.value ?? null,
});
export async function POST(req: Request) {
const session = await bb.auth();
if (!session) {
return Response.json({ error: 'Unauthorized' }, { status: 401 });
}
const { workspaceId } = await req.json();
const me = await bb.users.getProfile();
const allowed = await bb.permissions.check(
workspaceId,
me._id,
Permission.WORKSPACE_BILLING_MANAGE
);
if (!allowed) {
return Response.json({ error: 'Forbidden' }, { status: 403 });
}
return Response.json({ ok: true });
}Read more in the docs
Setup guides and reference for Access Control (RBAC).
Overview
Role-based permissions at the org and workspace level.
Checking permissions
Check permissions in code for conditional logic and gating.
Conditional rendering
Show or hide UI based on user roles and permissions.
Managing members
Invite members, assign roles, and track seat usage.
Admin API
Authenticate with an org API token and call the REST API behind the console modules.
Frequently Asked Questions
What people ask about Permissions.
Do my users see this?
Yes, through what they can do. Workspace owners and admins choose each teammate’s role, and every teammate sees only what that role allows.
Which roles are built in?
Admin, editor and viewer. New teammates join as editor, and the workspace owner always has every permission.
Can I add permissions for my own features?
Yes. Declare them per role in defaultPermissions on the provider and check them with can() or WhenPermission. BuildBase does not enforce them for you, so check them on your own server too, with hasPermission() from @buildbase/sdk.
Is hiding a button enough?
You do not have to rely on it. The API enforces the built-in permissions too, so a viewer who calls it directly still cannot invite people, change roles, manage billing or spend credits.