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.
The form
Section titled “The form”<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:
| Verb | Meaning | Approval |
|---|---|---|
read | Changes no shared object. A POST that searches or checks counts too. | None |
write | Creates or changes something. | Always a person |
delete | Deletes something. | Always a person |
The catalogue
Section titled “The catalogue”The current catalogue of the platform is open:
curl -s https://api.prudai.com/v1/scopesPer 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).
Wildcards and bundles
Section titled “Wildcards and bundles”- 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.
Who may do what
Section titled “Who may do what”| Caller | Permissions |
|---|---|
| Service key | Only the scopes on the key, within the organisation of the key. |
| User through login | The 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.
The effective permission
Section titled “The effective permission”One structure for the app, the API, the CLI and MCP. The effective permission is the intersection of four layers, followed by two checks:
- Product entitlement of the organisation: what the organisation has purchased.
- Organisation policy: what the organisation itself excludes.
- Roles of the user: roles are data in one register, products only know scopes.
- Token scope: what this token may do.
- Rights on the object: for example whether you may see this matter.
- 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.