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 can do now: a key that outgrows a demoted creator stops working, and removing someone from the organization revokes the keys they made.
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 });
}Access control for your own team, too
Roles and permissions for the people who run your app in the BuildBase console, and for the API keys they make.
Roles for your own team
Make your own roles for your team in the console. For each part of it, choose whether a role can view, create, change or delete. A support role, say, can look up users and change nothing.
API roles, kept apart
API keys get roles of their own, which can never be given to a person. So access you set up for an integration never ends up on someone's account.
Nobody hands out more than they hold
Nobody can make a role with permissions they don't have, or give anyone a role above their own. And an API key can never do more than the person who made it can do today.
Changes take effect at once
Remove someone and it applies the next time they do anything, not whenever their session would have run out. They're signed out, and every API key they made stops working. Change someone's role and their open console session switches to the new one.
Hand over ownership by offer
To give the organization to someone else, the owner sends an offer, and that person has seven days to accept. The other admins are told. Billing moves with it, and the old owner stays on as an admin.
Who changed what
An audit log with two tabs. One shows who joined, left, changed tier or took over ownership. The other shows what happened inside the organization: who got which role, who was blocked and who was issued an API key.
Works well with
Other modules for users & access.
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.
Your team and its roles
Roles for your own team and your API keys in the console, and how to hand the organization to someone else.
Mode and limits
Which workspace roles people can be given, the role new members start with and how many members fit, set in the console.
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, plus any roles you add. Someone who joins without a role gets viewer, and you can choose another default. The workspace owner always has every permission.
Can I add permissions for my own features?
Yes. Define them in the console under Workspaces > Settings and grant them per role in the permission matrix, or declare them per role in defaultPermissions on the provider. 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.
Can I limit what my own team can do in the console?
Yes. Under Settings, Roles, make roles for your team and choose what each one can view, create, edit or delete in each part of the console. API keys get roles of their own under API roles. Nobody can give out more access than they have, and a key never does more than the person who made it can do today.
Lock down the settings only admins should touch
Wrap the sensitive parts of your UI in WhenPermission. The BuildBase API already refuses member, billing and settings changes from roles that lack the permission.