Skip to content

Scopes and permissions

Every /v1 operation asks for a scope. The scope is in the spec (x-prudai-scopes), and so in the reference with every operation.

<product>:<object>:<verb>

For example prudai:sources:read or account:organizations:read. The verb is read, write or delete, and also sets the class for approvals:

VerbMeaningApproval
readChanges no shared object. A POST that searches or checks counts too.None
writeCreates or changes something.Always a person
deleteDeletes something.Always a person

The current catalogue of the platform is open:

Terminal window
curl -s https://api.prudai.com/v1/scopes

Per product the catalogue is derived from the spec: Prudai Developer API, IRMA (Prudai staff only, sign-in required) and ORDO (Prudai staff only, sign-in required).

  • Wildcard: only in the object position, such as prudai:*:read. A wildcard covers per call every issuable scope of that product and verb, except objects that can only be granted explicitly. Those are marked in the catalogue.
  • Bundle: expands to separate scopes when a key is issued. A bundle is no wildcard and gains no new rights later.
CallerPermissions
Service keyOnly the scopes on the key, within the organisation of the key.
User through loginThe rights of that user in the app. The token can only narrow them, never extend them.

A call without the right scope gets 403 insufficient_scope, with the required scope in details.required_scope. See Errors.

Internal scopes for Prudai staff can never be granted to a customer key.

One structure for the app, the API, the CLI and MCP. The effective permission is the intersection of four layers, followed by two checks:

  1. Product entitlement of the organisation: what the organisation has purchased.
  2. Organisation policy: what the organisation itself excludes.
  3. Roles of the user: roles are data in one register, products only know scopes.
  4. Token scope: what this token may do.
  5. Rights on the object: for example whether you may see this matter.
  6. Approval: whether a person must look along.

Refusing wins: if a piece of data is missing or a scope is unknown, the answer is no.