Authorization

Authentication answers "who are you?". Authorization answers the next two questions: may you act here at all, and may you perform this specific action. Every screen in the generated app and every table in its database answers those questions the same way, and this page is the map of that system.

The design is attribute-based access control (ABAC): a decision can consult any attribute of the user and the thing being acted on. Roles are the most important attribute, so day to day it feels like classic role-based access, but nothing limits a rule to roles, and the last section shows a rule that never mentions one.

Two layers, one answer

Every check exists twice, on purpose:

• The app checks first, as a courtesy. A synchronous user.can(...) call decides whether a button, tab or menu item is even shown. Its only job is a good experience: nobody should see controls they are not allowed to use.
• The database checks again, as the authority. Every query runs through row-level security, which re-evaluates the same rules server-side. This is the layer that actually protects data.

A tampered or buggy client can skip the first layer; it can never skip the second. That is why the docs keep repeating the same sentence in different forms: hiding a button is a courtesy, row-level security is the law.

Both layers fail closed around the same attribute: a deactivated membership resolves to zero roles. The app stops offering anything, and the database stops matching any permission, without either side needing a special case.

Roles and permissions

INSERT INTO public.roles (slug, name, description) VALUES
    ('owner', 'Owner', 'Organization owner with full administrative privileges');
-- ...
INSERT INTO public.roles_permissions (role_id, permission_id)
SELECT r.id, p.id
FROM public.roles r, public.permissions p
WHERE r.slug = 'admin'
AND p.slug IN (
    'billing.manage',
    'invites.create',
    -- ...
);

INSERT INTO public.roles (slug, name, description) VALUES
    ('auditor', 'Auditor', 'Read-only access for compliance review');

INSERT INTO public.roles_permissions (role_id, permission_id)
SELECT r.id, p.id
FROM public.roles r, public.permissions p
WHERE r.slug = 'auditor'
AND p.slug IN (
    'memberships.read',
    'users.read',
    'usersroles.read'
);

enum Role {
  owner('owner'),
  admin('admin'),
  member('member'),
  auditor('auditor');

  // ...

  int get priority {
    return switch (this) {
      Role.owner => 3,
      Role.admin => 2,
      Role.member => 1,
      Role.auditor => 0,
    };
  }
}

Checking in the database

Nine SQL helpers answer authorization questions, and all nine are granted to authenticated, so you can call any of them from your own policies, functions and queries. Permissions are covered below; entitlements and step-up have sections of their own further down.

The generated project documents every helper, including the ones this page skips, in supabase/docs/helpers_catalog.md.

CREATE POLICY "Members with the permission can update projects"
ON public.projects
FOR UPDATE TO authenticated
USING ((SELECT app.has_perm(organization_id, 'projects.update')));

Entitlements: what the plan allows

Permissions answer "may this role do it". Entitlements answer a different question: "does this plan include it". They are a second axis with the same shape: plans are to entitlements exactly what roles are to permissions, down to sharing the same wildcard matching.

The kit ships the machinery empty. Entitlement slugs are your product's vocabulary (reports.advanced, exports.csv, api.access), so the tables exist, the check function exists, and a commented worked example waits in supabase/db_seeds/seed.sql; nothing is seeded because nothing generic would be right.

The check is app.has_entitlement, which consults the caller's own subscription; called with an organization Multi-tenancy only it consults the organization's subscription instead. A feature that should be gated by both axes composes them:

-- The member's role may read reports AND the org's plan includes them.
(SELECT app.has_perm(organization_id, 'reports.read'))
AND (SELECT app.has_entitlement(organization_id, 'reports.advanced'))

Because a plan keeps its entitlement rows even after you retire it, grandfathering comes free: legacy subscribers keep exactly what their plan granted, and new plans grant whatever you decide next.

Step-up checks

Some actions are dangerous enough that being signed in, even with the right role, is not enough; the kit wants proof that it is really you, recently. That is a third axis, orthogonal to the other two, carried by three helpers:

• app.has_recent_totp_verification(...) demands a fresh TOTP code and fails for users who never enrolled an authenticator. Deleting an organization requires it, and both sides of an ownership transfer prove themselves with it.
• app.has_recent_identity_verification(...) is the softer sibling: enrolled users must present a fresh TOTP code, everyone else a recent sign-in. Account deletion uses it, so not having MFA never blocks leaving.
• app.mfa_satisfied() is the session-level floor: users with a verified authenticator must be in an MFA-verified session; everyone else passes.

The app-side twin of these checks, including the freshness window and how the prompt appears, is covered in Step-up verification.

Checking on the client

The Dart side lives in lib/core/domain/authz/ and mirrors the database in spirit: policies group the rules for one domain, actions are enums, and the check is a plain synchronous call on the current user:

final canInvite = user.canInOrg(const OrganizationPolicy(), OrgAction.invite);

That is the whole API surface most screens need: resolve the user's roles in the current organization, ask the policy, show or hide accordingly. Role resolution fails closed; no current organization, no matching membership, or a deactivated one all resolve to zero roles, and every check answers no.

Rules are composed from a small permission algebra, and the When predicate is where the attribute-based part shows: it can consult anything about the user and the data. The member-management policy uses it for "never on yourself, never on the owner"; your own rules can go further and skip roles entirely:

// Comments are editable by their author, once, within five minutes.
final canEdit = When<Comment>((u, c) {
  final isAuthor = c.authorId == u.id;
  final isRecent = DateTime.now().difference(c.createdAt).inMinutes < 5;
  return isAuthor && !c.isEdited && isRecent;
});

user.check(canEdit, data: comment);

The full authoring guide, including custom policies, global (non-organization) policies and role resolvers, is in the generated project at lib/core/domain/authz/README.md.

What's next?