Scopes and Permissions
Understand how Read Only and Read & Write credentials map to API scopes, and which scope each endpoint requires.
Scopes control which endpoints a credential can call. You don't pick scopes one by one. Instead, the access level you choose when you create a credential, Read Only or Read & Write, decides which scopes the credential gets.
Access Levels and Scopes
| Access level | Scopes granted | What the credential can do |
|---|---|---|
| Read Only | policy:read, control:read, evidence:read, framework:read, test:read, vulnerability:read | List and read data across all six modules |
| Read & Write | Every Read Only scope, plus policy:write, control:write, evidence:write, framework:write, test:write, vulnerability:write | Everything Read Only can do, plus upload evidence attachments and create or update vulnerability findings. Important: Currently, policy:write, control:write, framework:write, test:write work the same as policy:read, control:read, framework:read, test:read respectively. |
You set the access level under Scope when you create a credential in Settings → Developer Console in Scrut. See Create API Credentials.
Heads Up! Access levels apply to your entire organization. You can't limit a credential to specific modules or entities. Anyone with the credential can access all data its access level permits.
Check Your Credential's Scopes
The scope field in the token response lists every scope your credential has, as a comma-separated string:
{
"scope": "control:read, evidence:read, framework:read, policy:read, test:read, vulnerability:read"
}
If a call returns 403 forbidden, check this field to confirm whether the credential has the scope that endpoint needs.
Scope Reference
Scopes follow the format {resource}:{action}.
| Scope | Allows |
|---|---|
policy:read | List and read policies. |
policy:write | List and read policies. Currently equivalent to policy:read. |
control:read | List and read controls. |
control:write | List and read controls. Currently equivalent to control:read. |
evidence:read | List and read evidence. |
evidence:write | Upload evidence attachments. Also allows reading evidence. |
framework:read | List frameworks. |
framework:write | List frameworks. Currently equivalent to framework:read. |
test:read | List and read tests. |
test:write | List and read tests. Currently equivalent to test:read. |
vulnerability:read | List and read vulnerabilities. |
vulnerability:write | Create or update vulnerabilities. Also allows reading. |
Endpoints That Need Read & Write
Only three endpoints write data. Each needs a Read & Write credential:
| Endpoint | Scope required |
|---|---|
POST /v1/evidence/{evidenceId}/attachments | evidence:write |
POST /v1/vulnerabilities | vulnerability:write |
PATCH /v1/vulnerabilities/{vulnerabilityId} | vulnerability:write |
All other endpoints work with a Read Only credential.
How Scopes Are Checked
- A
writescope includes read access to the same resource only. - Each module needs its own scope. For example,
policy:readdoesn't grantevidence:read. - Calling an endpoint without the required scope returns
403 forbidden. - If your Scrut plan doesn't include a resource, the call returns
403 plan_restricted, even when the credential has the scope.
Contact support@scrut.io for further assistance.