API FundamentalsScopes and Permissions

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 levelScopes grantedWhat the credential can do
Read Onlypolicy:read, control:read, evidence:read, framework:read, test:read, vulnerability:readList and read data across all six modules
Read & WriteEvery Read Only scope, plus policy:write, control:write, evidence:write, framework:write, test:write, vulnerability:writeEverything 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}.

ScopeAllows
policy:readList and read policies.
policy:writeList and read policies. Currently equivalent to policy:read.
control:readList and read controls.
control:writeList and read controls. Currently equivalent to control:read.
evidence:readList and read evidence.
evidence:writeUpload evidence attachments. Also allows reading evidence.
framework:readList frameworks.
framework:writeList frameworks. Currently equivalent to framework:read.
test:readList and read tests.
test:writeList and read tests. Currently equivalent to test:read.
vulnerability:readList and read vulnerabilities.
vulnerability:writeCreate or update vulnerabilities. Also allows reading.

Endpoints That Need Read & Write

Only three endpoints write data. Each needs a Read & Write credential:

EndpointScope required
POST /v1/evidence/{evidenceId}/attachmentsevidence:write
POST /v1/vulnerabilitiesvulnerability:write
PATCH /v1/vulnerabilities/{vulnerabilityId}vulnerability:write

All other endpoints work with a Read Only credential.

How Scopes Are Checked

  • A write scope includes read access to the same resource only.
  • Each module needs its own scope. For example, policy:read doesn't grant evidence: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.