How Raff splits access into Account-level and Project-level roles, why account-level grants don’t include project-level visibility, what the seven prebuilt System roles do, and how to build Custom roles
Updated May 8, 2026This is the model page for permissions on Raff. Read it once and the Roles tab on the Team & Projects page makes sense. The two big ideas:
Account and Project are separate authorization domains. Granting account-level permissions does not grant access to projects’ resources. Project access is granted explicitly, per project, on top.
The first user (the Owner) has everything. Every other member you invite gets a deliberately narrower scope.
Every permission in Raff is prefixed with one of two domains:
Permission prefix
Domain
What it controls
account.*
Account-level
Things that affect the whole account — who’s invited, billing, account settings, audit log, account-wide API keys, the list of projects
project.* and resource-level (vm.*, vpc.*, …)
Project-level
Things that exist inside a project — VMs, VPCs, public IPs, members of this project, project settings
A member can hold roles in both domains independently. They can have the Admin account role and a Viewer project role on customer1 — those are two separate grants, evaluated separately.Crucially: an account-level role doesn’t grant project-level access automatically. If a member has Admin (account) but no project role on customer1, they cannot list, view, or touch any VM in customer1. They can manage account settings, invite members, generate API keys — but they have zero visibility into the actual workloads running inside projects unless explicitly granted a project role.This is the safety property the model is designed around. Compliance, ops, and billing folks can hold powerful account-level roles without seeing customer data.
The user who signs up the account is the Owner. This is automatic; you don’t pick it.
Property
Value
Granted automatically
At signup, to whoever creates the account
Permissions
Full access — every account permission and every project permission, on every project, current and future
Number of Owners
Exactly one per account today
Transferable?
Via support — the Owner badge can be moved to another account-level member, but you can’t have two Owners simultaneously
Removable?
No — the Owner is the account’s last-resort administrator; removing them would orphan the account
The Owner badge is the orange tag you see on the first row of the Members list. Every other member shows either Account (the role you assigned at the account level) or Project-only (no account role; project roles only).
The Roles tab on the Team & Projects page is where you see and manage all the role definitions in your account.
The tab is split by domain:
ACCOUNT ROLES — applied to a member at the account level. The screenshot shows 3 system-provided ones
PROJECT ROLES — applied to a member on a specific project. The screenshot shows 4 system-provided ones
The Scope filter at the top (All / Account / Project) lets you focus on one domain at a time. The + Create Role button creates a Custom role — see the dedicated section below.Every row’s eye icon opens the role’s permission view. The +N more badge tells you how many additional permissions the row hides — click the eye icon to see them all.The ⋮ menu offers different actions depending on the role’s type:
Role type
Available actions
System
Duplicate only — creates a Custom role pre-filled with this System role’s permissions. Edit / Delete are not offered because System roles can’t be modified
Custom
Edit (change permissions, name, description), Duplicate (clone into another Custom role), Delete (when no member holds it)
Roles come in two types, shown by the Type column:
Type
What it means
System
Built-in by Raff. Predefined permission sets for the most common patterns. Cannot be edited or deleted — but you can copy a System role into a Custom one and tweak from there
Custom
Roles you create with + Create Role. You pick the domain (Account or Project), name it, and toggle every permission on or off. Edit and delete any time
The 7 System roles ship with every account. Most teams never need to create Custom roles — pick from the predefined ones until you genuinely need something the System set doesn’t cover.For the full list of System roles and what each one’s permissions add up to, see Permissions matrix.
What a role’s permissions look like — Account example
Click the eye icon on the Admin account role to see what it actually grants.
A few takeaways from this view:
Permissions are grouped by category — Projects, Members, Roles, API Keys, Billing, Account Settings, Audit Log. Each category shows (enabled / total) so you can see the role’s coverage at a glance.
The Admin role intentionally excludes destructive and billing permissions — account.projects.delete, account.members.remove, account.roles.delete, account.apikeys.revoke, and the entire Billing category are all OFF. The role description (Account admin without billing) reflects this.
System roles can’t be modified — the toggles render but submission is blocked. To change behavior, copy into a Custom role.
Permission names are dot-separated in <domain>.<resource>.<action> form. Predictable and greppable.
When a member tries to do anything in the dashboard or via the API, Raff checks the action against their grants:
Is the action an account.* permission? └─ YES → Check the member's Account-level role. ALLOW if the role has the permission, DENY otherwise.Is the action a project.* / vm.* / vpc.* permission on project X? └─ YES → Check the member's Project-level role on project X. (NOT their account role — these are separate domains.) ALLOW if the role has the permission, DENY otherwise. DENY if the member has no role on project X at all.
A member with only an account-level role can navigate the Team & Projects page, see the account settings, work with billing if their role allows, and so on — but they get an empty list under Compute, Networking, and every other resource page until you grant them a project role somewhere.
Pick the Scope carefully — it’s locked after create. When you create a Custom role, the Scope dropdown (Account or Project) cannot be changed later. The two domains use different permission catalogs (21 account permissions vs 40 project permissions), so there’s no migration path. If you pick the wrong one, you have to delete the role and rebuild it from scratch — which means re-assigning every member or API key currently using it. Decide before you click Save: is this a role for account-wide responsibilities (members, billing, audit, projects list) or for resources inside one or more projects (VMs, VPCs, IPs, snapshots)?
Reach for a Custom role when:
You need a permission combination none of the System roles offers (e.g. “can manage VMs but cannot delete them and cannot manage VPCs”)
You want to remove a single permission from a System role for a specific subset of members
You’re building a least-privilege role for a script / API key (give exactly the permissions the automation needs, nothing more)
There are two ways to create a Custom role, and which you pick matters:
Option 1 — Duplicate a System role (recommended starting point)
The fastest way: pick the System role closest to what you want, click ⋮ → Duplicate. A new Custom role is created with the System role’s exact permission set, and you tweak from there. Most teams need a small variation on a System role — duplicate, rename, toggle one or two permissions, save.The duplicate inherits the scope (account vs project) of the source — duplicating Project Admin produces a Project-scoped Custom role; duplicating Admin produces an Account-scoped one.
Option 2 — Create from scratch via ”+ Create Role”
The right path when no System role is close to what you want, or when you’re building a tightly-scoped role for automation. Click + Create Role in the top right of the Roles tab.
The dialog has four blocks:
Field
What goes here
Role Name
A short label — Developer, Read-only auditor, CI deployer. Must be unique across all roles in the account
Description(optional)
Free-form. Useful for telling teammates what this role is for
Scope
Dropdown — Account - For account-wide accessorProject - For project-specific access. Pick one; you cannot change it after creation. The helper text spells it out: “Account roles apply to the entire account. Project roles apply only within specific projects.”
Permissions
The full toggleable catalog for the chosen scope, grouped by category
A few things about the Permissions area worth knowing:
The total count depends on the scope. Account scope shows 21 permissions; Project scope shows 40 permissions. The live counter (0 / 21 selected) updates as you toggle.
Bulk actions:Select All / Clear All at the top apply to the whole catalog.
Per-category None: the None checkbox on the right of each category header turns off every permission in that category in one click — useful when you want everything except a specific category (e.g. “every Account permission except Billing”).
Categories show their coverage:(N/M) next to each category name — (0/4), (2/4), (4/4) — so you can see a role’s shape at a glance without expanding it.
The Scope dropdown is the most consequential choice in this dialog because it’s locked after creation:
Pick Account for roles that mix account-wide responsibilities — think “billing + audit”, “members admin without project access”, “support engineer with audit-only access”
Pick Project for roles that touch project resources — anything involving VMs, VPCs, IPs, project members, project settings
If you find you picked the wrong scope, the workaround is to delete the role and re-create it with the right scope. You can’t migrate permissions across scopes; the catalogs are different sets.
API keys are created with the same Account / Project role pair members get — the key’s permissions come from a role you pick at create time, not from the creator’s identity.The Create API Key flow asks for:
Account Role — the key’s account.* permission set (Owner / Admin / Billing / Member, or a Custom Account role)
Project Role + projects — the key’s project.* permission set, applied to one or more selected projects (skipped when Step 1 is Owner, since Owner covers everything)
Expiration — auto-revoke after a fixed time
Permissions Preview — the live preview of the resulting permission set
The combination is frozen onto the key at create time. Editing a member’s role later doesn’t change any keys; the key carries its own role assignment. To change what a key can do, you either rotate the key with a different role, or edit the role definition itself — which then changes the key’s access (and every other grant using that role).This is the centralized role system in action: roles are the single source of truth, and members and keys both reference them. See Generate an API key for the dashboard walkthrough.
