Roles and permissions
Should your team lead be a Security admin or an AppSec engineer? Picking the bigger role because it is easier is how most access reviews end up failing.
Start with the smallest built-in role that fits, and write a custom role only when none does. A role is a set of permissions, and it grants nothing until a group uses it.
Built-in roles
You cannot change a built-in role. To change what one allows, create a custom role.
| Role | Who it is for | Permissions |
|---|---|---|
| Administrator | Everything, on every organization. Only the Administrators group has it. | 113 |
| Security admin | Every organization-level permission. Reads access control and the audit log, but cannot change members, roles, billing or security settings. | 90 |
| AppSec engineer | Day to day security work: triage, scans, fixes, tests and policies, but not enforcing them. | 59 |
| Developer | Reads everything on its organizations and fixes its own findings. | 26 |
| Approver | An add-on, given in its own group: approves tests and exceptions, enforces policies, accepts risk. | 8 |
| Viewer | Reads everything on its organizations. | 19 |
| Auditor | Viewer plus read-only access to the audit log, members, roles, keys, security and billing. Bind it at the root. | 30 |
| Billing admin | Usage and billing. | 4 |
| CI pipeline | Service accounts in CI/CD: upload specs and SBOMs, run scans, read findings and policies. | 8 |
The full list of who holds what is in Permissions.
The split worth keeping: Approver
AppSec engineers can write policies, tests and exceptions, but they cannot enforce a policy, approve a test or approve an exception. Approver holds exactly those powers, so a second person gets to say yes. Give it in its own group, to a small set of people. A custom role that combines the two throws away the separation.
Two levels of permission
| Level | Where it counts |
|---|---|
| Organization | On the organization a group grants it on, and on every child. |
| Tenant | Only when a group grants it on the root organization. |
A role with any tenant-level permission can only be granted on the root organization. The console refuses a group, an invite or a role change that would bind one anywhere else, with the error validation and the message "this role has tenant-level permissions and can only be granted on the root organization". If a custom role needs members:read but should stay inside one organization, split it: keep the organization-level permissions in one role for that organization, and grant the tenant-level ones on the root.
Create a custom role
You need roles:create.
- Open Settings › Members, then Roles, and choose New role.
- Name it after who gets it, and add a description.
- Pick the permissions. You can only grant permissions you hold yourself, and the picker marks the rest as unavailable.
- Save.
- Create or edit a group to use it. Until then, it grants nothing.
What you should see
The role is listed as Custom. You can only delete a role no group uses.
Try this next
Open a built-in role in Settings › Members and read its permissions. Then ask whether your team needs all of them. If you are about to grant Security admin to someone who only triages findings, AppSec engineer is the right answer. Next, give your pipelines their own identity with service accounts.