Roles and permissions

Access has two separate systems, and confusing them is the usual source of "why can they see that?":

• User roles describe a person. One role per user, carried in their session.
• API key scopes describe a program. Functional boundaries on a key, not a role.

They are checked the same way - does the caller carry a value this endpoint accepts - but they are not interchangeable. A role is not a scope and a scope is not a role.

User roles

Role	For
org_admin	Full administration of one organization
pentester	Assessment work: findings, scanners, engagements
engineer	Fixing things: findings and the assets they sit on
developer	Application security: repositories, code findings
soc_analyst	Security operations: alerts, incidents, detection tuning
auditor	Read-only. For people who need evidence, not access
risk_approver	Approving risk acceptance requests
billing_admin	Subscription, plan, payment method
project_manager	Engagement scheduling and coordination

Two more exist and are not assigned to customer users:

Role	For
staff	Service-provider personnel operating on your behalf
superuser	Platform administration across organizations

Choosing one

Most people are engineer or developer. Those two roles cover seeing findings on things you own and doing something about them, which is what the majority of a security programme actually consists of.

Reach for the narrower roles deliberately:

• auditor is genuinely read-only. Give it to anyone who needs to see your posture without acting on it - compliance, leadership, an external assessor. It is safer than engineer and almost always what such a person actually needs.
• risk_approver separates deciding-not-to-fix from doing-the-fixing. Worth splitting if your process requires someone other than the implementer to accept a risk.
• billing_admin exists so that whoever holds the budget does not need administrative access to the security data.

org_admin can do everything within an organization, including adding users and changing their roles. Keep the number small.

Roles and business units

A role says what someone can do. A business unit says what they can do it to.

The two combine: an engineer scoped to a business unit sees findings on that unit's assets and not the rest of the estate. That is what makes a findings queue usable for a team, and what stops an organization-wide list being ignored by everyone.

See Organizations, business units, and zones.

API keys

An API key is for a program - CI pipelines, scripts, integrations you build yourself. It carries scopes, not a role, so it can be narrowed to exactly what the program needs:

Scope	Allows
assets:read	List and get hosts, web apps, cloud resources, and EDR devices
findings:read	List, search, get, and export findings
findings:write	Create and update findings and remediations
vulnerabilities:read	List, search, get, and export vulnerabilities
vulnerabilities:write	Update vulnerability status, risk acceptance, and assignee
scans:trigger	Trigger vulnerability, DAST, and SAST scans
soc:read	List and get alerts and incidents
soc:write	Create and update alerts and incidents
jira:read	List and get Jira tickets and rules
jira:write	Create and update Jira tickets
reports:read	List and download generated reports
reports:write	Generate reports and create schedules

Grant the minimum. A pipeline that triggers a scan and reads the result needs scans:trigger and vulnerabilities:read - it does not need write access to anything, and a key that has it is a key that can silently close findings.

See API keys.

A key is a credential

Anyone holding it has its scopes, with no second factor and no user attached. Store keys in a secret manager rather than in a repository or a pipeline definition, and rotate them on the same schedule as anything else that grants access.

Next

• Users - inviting people and assigning roles
• Identity providers - single sign-on
• API keys - creating and scoping keys