> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veridox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions and API Keys

> Which permission each endpoint needs, and how API keys use them.

## 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 returns `403`. A record the caller cannot reach returns `404`, so the API does not reveal that it exists.

## Permissions

| Permission | Allows | Owner | Admin | Analyst | Member |
| - | - | :-: | :-: | :-: | :-: |
| `organisation_cases:read` | See every case and document request in the organisation, not only your own | ✓ | ✓ | | |
| `organisation_cases:write` | Create cases, update case labels, and create, resend or void document requests | ✓ | ✓ | ✓ | ✓ |
| `organisation_files:read` | See every file in the organisation, not only your own | ✓ | ✓ | | |
| `organisation_files:write` | Upload files | ✓ | ✓ | ✓ | ✓ |
| `organisation_files:reassign` | Move a file to another case | ✓ | ✓ | ✓ | |
| `organisation_files:override_risk_score` | Change a file's risk score | ✓ | ✓ | ✓ | |
| `organisation_files:delete` | Archive files | ✓ | ✓ | | |
| `organisation_files:purge` | Permanently delete files (early access) | ✓ | | | |
| `organisation_members:read` | View the organisation's members | ✓ | ✓ | | |
| `organisation_members:write` | Change members' roles | ✓ | ✓ | | |
| `organisation_teams:read` | View teams | ✓ | ✓ | ✓ | ✓ |
| `organisation_teams:write` | Create and change teams | ✓ | ✓ | | |
| `organisation_teams:delete` | Delete teams | ✓ | ✓ | | |
| `organisation_settings:read` | Read organisation settings, the role permissions and the audit log | ✓ | ✓ | | |
| `organisation_settings:write` | Change organisation settings and role permissions, and manage API keys and webhooks | ✓ | | | |
| `billing:read` | View billing | ✓ | ✓ | | |
| `billing:write` | Manage billing | ✓ | | | |

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](/api-reference/endpoints/org-role-permissions-get.md).

## 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](/guides/document-requests.md) into a case they created. The `organisation_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 with `organisation_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:read` or `organisation_files:read`. Without either, list and search endpoints return no results, or `400` if you pass `scope=org`, and other endpoints return `404`.
* **A permission that changes a resource also grants read on it.** A key holding any of `write`, `delete`, `reassign`, `override_risk_score` or `purge` on a resource is treated as also holding that resource's `read`. For example, a key with `organisation_files:write` can 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.

A key that lacks a permission receives `403`:

```javascript theme={null}
const response = await fetch('https://api.{region}.veridox.ai/organisations/audit-log', {
  headers: { 'X-API-Key': apiKey }
});

// A key without organisation_settings:read:
// 403 { "error_code": "request.organisations.permission.denied", ... }
console.log(response.status);
```

Some actions taken with an API key are recorded in the [audit log](/api-reference/endpoints/org-audit-log-get.md), with `actor_type` set to `api_key`. See that page for which actions are recorded and how the key is named.

> [!NOTE]
>
> Called with an API key, [Get Current User](/api-reference/endpoints/users-me.md) 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](/api-reference/endpoints/auth-status.md) 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.

| Endpoint | API key needs |
| - | - |
| [Create Case](/api-reference/endpoints/cases-create.md) | `organisation_cases:write`, plus `organisation_files:write` when you include `file_labels` |
| [List Cases](/api-reference/endpoints/cases-list.md) | `organisation_cases:read` |
| [Get Case](/api-reference/endpoints/cases-get.md) | `organisation_cases:read`, plus `organisation_files:read` to see the case's files |
| [Update Case Label](/api-reference/endpoints/cases-update-label.md) | `organisation_cases:write` |
| [Upload Files to Case](/api-reference/endpoints/cases-files-upload.md) | `organisation_cases:read` and `organisation_files:write` |
| [Progress Stream](/api-reference/endpoints/cases-progress-stream.md), [Progress Poll](/api-reference/endpoints/cases-progress-poll.md) | `organisation_cases:read`, plus `organisation_files:read` for per-file events |
| [List Files](/api-reference/endpoints/files-list.md), [Search](/api-reference/endpoints/search.md) | `organisation_files:read` |
| [Get File Analysis](/api-reference/endpoints/files-analysis-get.md), [Get Asset URL](/api-reference/endpoints/files-asset-url-get.md), [Bulk Download](/api-reference/endpoints/files-download-bulk.md) | `organisation_files:read` |
| [Confirm Risk Score](/api-reference/endpoints/files-risk-confirm.md) | `organisation_files:read`; `organisation_files:override_risk_score` to change the score |
| [Reassign File](/api-reference/endpoints/files-reassign.md) | `organisation_files:reassign` and `organisation_cases:read` |
| [Archive File](/api-reference/endpoints/files-archive.md) | `organisation_files:delete` |
| [Delete File](/api-reference/endpoints/files-delete.md) (early access) | `organisation_files:purge` |
| [List](/api-reference/endpoints/document-requests-list.md) or [Get](/api-reference/endpoints/document-requests-get.md) Document Requests | `organisation_cases:read`, plus `organisation_files:read` to see the files a recipient uploads |
| [Create](/api-reference/endpoints/document-requests-create.md), [Resend](/api-reference/endpoints/document-requests-resend.md) or [Void](/api-reference/endpoints/document-requests-delete.md) a Document Request | `organisation_cases:write` |
| [Get Role Permissions](/api-reference/endpoints/org-role-permissions-get.md), [Get Audit Log](/api-reference/endpoints/org-audit-log-get.md), [Get Verification Setting](/api-reference/endpoints/org-verification-get.md) | `organisation_settings:read` |
| [Update Verification Setting](/api-reference/endpoints/org-verification-update.md) | `organisation_settings:write` |
| [Get Branding Logo](/api-reference/endpoints/org-branding-get.md), [Get Current User](/api-reference/endpoints/users-me.md) | No permission |
| [Authentication Status](/api-reference/endpoints/auth-status.md), [Server Status](/api-reference/endpoints/status.md) | No permission; no authentication required |

Document request endpoints also need the Document Requests feature module, and the verification endpoints need the verification feature. See [Feature Modules](/guides/feature-modules.md).

## Related Resources

> **[Get Role Permissions](/api-reference/endpoints/org-role-permissions-get.md)**
>
> See which permissions each role holds in your organisation

> **[Get Audit Log](/api-reference/endpoints/org-audit-log-get.md)**
>
> Review changes made in your organisation

> **[Authentication Status](/api-reference/endpoints/auth-status.md)**
>
> Check an API key and the permissions it holds

> **[Error Handling](/guides/error-handling.md)**
>
> Permission and validation error codes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.