Roles & permissions

Atlas authorization is role-based access control (RBAC) scoped to an organization. A role is a named bundle of permissions; a member holds one or more roles; your app checks permissions.

Built-in roles

Every organization starts with sensible defaults you can extend:

• org:admin — full control of the organization (members, settings, billing).

• org:member — read and contribute.

Permissions

A permission is a fine-grained verb on a resource, written resource:action or scope:resource:action, for example:

org:members:manage
org:billing:manage
project:read
project:write

You define the permissions that make sense for your product and assign them to roles.

Create a custom role

1. Open Organizations → Roles (or the instance-level role settings).

2. Choose Create role, give it a key like org:billing and a name.

3. Select the permissions it grants.

4. Assign the role to members from Members.

Checking access in your app

Roles and permissions are included in the verified session token, so checks are fast and need no extra round-trip.

On the server:

// Allow only if the user has the permission in the active org
if (!has({ permission: 'org:members:manage' })) {
  return forbidden();
}

// Or guard a whole handler
protect({ role: 'org:admin' });

In your UI:

<Protect permission="org:billing:manage">
  <BillingSettings />
</Protect>

<Protect> renders its children only when the current user has the required role or permission in the active organization.

Fine-grained access (FGA)

When authorization depends on a specific object — "Ada may edit document 42, but not document 7" — global roles aren't enough. Atlas also offers a Zanzibar / OpenFGA-style relationship model for per-object permissions. Use RBAC for broad capabilities and FGA for object-level sharing.

Custom JWT claims

On Pro and above you can inject custom claims into the session token (plan tier, feature flags, tenant settings) so your services authorize straight from the verified token.

Next

Understand the active-organization concept your checks rely on → Organization context & switching.