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.
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.
You set the access level under Scope when you create a credential in Settings → Developer Console in Scrut. See Create API Credentials.
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. |
Note: Currently, policy:write, control:write, framework:write, and test:write work the same as policy:read, control:read, framework:read, and test:read, respectively.
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.