Skip to content
Access Control (RBAC)

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.

components/team-page.tsxTSX
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 />}
    </>
  );
}
app/api/billing/route.tsTSX
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.

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.

Free plan7-day free trial on paid plansNo credit card required