Overview
Access in Veridox is controlled by permissions. Each person in your organisation has a role, and each role grants a set of permissions. Each API key carries its own list of permissions, chosen when the key is created. An endpoint that needs a permission the caller lacks returns403. A record the caller cannot reach returns 404, so the API does not reveal that it exists.
Permissions
The ticks show each role’s defaults. Anyone with
organisation_settings:write can change, in the Veridox dashboard, which permissions the roles below their own hold for your organisation. The Owner role always holds every permission. To see the permissions in force for your organisation, call Get Role Permissions.
Your Own Records and Everyone Else’s
A person can always reach the cases and files they created, including files that recipients upload through a document request into a case they created. Theorganisation_cases:read and organisation_files:read permissions extend that to every case or file in the organisation.
Reaching a record does not let you change it. Each change also needs its own permission: archiving a file you uploaded still needs organisation_files:delete.
API Keys
Anyone withorganisation_settings:write creates and revokes API keys in the Veridox dashboard. You cannot manage API keys through the API.
When you create a key, you choose its permissions. A new key has no permissions unless you grant them. You cannot grant a key a permission you do not hold yourself; if you try, the request fails with 400 and request.organisations.api-key.permission-exceeds-access. A key’s permissions cannot be changed after it is created; to change them, create a new key and revoke the old one.
A key keeps the permissions it was created with, even if its creator’s role or permissions change later. Keys created before permissions were introduced were given full access to cases, files, members, teams and settings. They do not hold organisation_files:purge, billing:read or billing:write.
An API key works differently from a person:
- It acts only through its own permissions. It does not take on the role or permissions of the person who created it.
- It never counts as the creator of a record. Records a key creates, such as cases and files, are attributed to the person who created the key, so that person sees them as their own. The key itself does not. To read or act on any case or file, a key needs
organisation_cases:readororganisation_files:read. Without either, list and search endpoints return no results, or400if you passscope=org, and other endpoints return404. - A permission that changes a resource also grants read on it. A key holding any of
write,delete,reassign,override_risk_scoreorpurgeon a resource is treated as also holding that resource’sread. For example, a key withorganisation_files:writecan read every file in the organisation. - Some actions are never available to a key, whatever its permissions: creating, listing, viewing or revoking API keys, changing role permissions, and changing a member’s role.
403:
actor_type set to api_key. See that page for which actions are recorded and how the key is named.
Called with an API key, Get Current User returns the person who created the key:
organisation.role and organisation.permissions are that person’s, not the key’s. To see the key’s own permissions, call Authentication Status and read permissions.Permissions by Endpoint
Every endpoint in this reference can be called with an API key. The table lists the permissions the key needs.
Document request endpoints also need the Document Requests feature module, and the verification endpoints need the verification feature. See Feature Modules.
Related Resources
Get Role Permissions
See which permissions each role holds in your organisation
Get Audit Log
Review changes made in your organisation
Authentication Status
Check an API key and the permissions it holds
Error Handling
Permission and validation error codes