Introduction
API Tokens allow external tools — including the ComplyFlow MCP Server and AI assistants — to read your ComplyFlow data securely. This guide explains how to create a token, how scopes and permissions work, and how to revoke a token you no longer need.
Creating an API Token
You need permission to manage API tokens. If API Tokens does not appear in your user menu, ask your account administrator to enable API access for your Staff User account.
1. Sign in to ComplyFlow as a Staff User
2. Open the user menu (top right) and select API Tokens. The page is titled Personal API Tokens
3. Select New token
4. The Token Creation Form will be shown and you need to:
a. Enter a descriptive Name for the token, e.g. Claude Code – Safety Team
b. Select the Scopes the token needs (see Understanding Scopes below)
c. Under Expires in, choose how long the token should last — 7, 30, 60 or 90 days, 1 year, or a custom date up to a maximum of 1 year. New tokens default to 30 days
5. Select Create token
6. Copy the token and store it somewhere secure, such as a password manager
Your token is displayed once only. ComplyFlow stores it in a protected, irreversible format and cannot show it to you again. If you lose a token, revoke it and create a new one.
ComplyFlow API Tokens always begin with cf_pat_, which makes them easy to recognise in configuration files.
You can hold up to 10 active tokens at a time. If you reach the limit, revoke a token you no longer use before creating a new one.
Understanding Scopes
Scopes control which modules a token is allowed to read. A token can only access data in the modules you tick when creating it. All scopes are read only — no token can create, change or delete data. You must select at least one scope; a token with no scopes cannot be created.
Group | Scope | What it allows the token to read |
Sites & projects |
| Site details and configuration, who is engaged at each Site, and Site Documents |
People |
| Staff Users, including their Documents and Training records |
People |
| Suppliers/Contractors and their Workers, including their compliance Documents |
Operational |
| Incidents |
Operational |
| Inspections, including findings and actions |
Operational |
| Plant & Equipment |
Operational |
| Risk Register, including assessments and actions |
Operational |
| Permits |
There is no separate scope for Documents or Training. These are read through the scope of the record they belong to: Supplier/Contractor and Worker Documents through contractors:read, Site Documents through sites:read, and Staff Documents and Training through staff:read.
As a rule, grant the fewest scopes the integration needs. You can always create another token with broader scopes later.
How permissions work
Scopes are only one of the checks applied to every request. A token can never grant more access than you have yourself:
Your module permissions — the token inherits your Staff User permissions. If your account cannot view Incidents, a token with
incidents:readstill returns no Incident dataYour Site assignments — if your access is restricted to particular Sites, the token only returns data for those Sites
Your organisation — a token only ever reads data from your own organisation
Expiry — once a token passes its expiry date, all requests are rejected until you create a new token
If your Staff User account is deactivated, your tokens stop working with it.
Revoking a token
1. Open the user menu and select API Tokens
2. Find the token in the list
3. Select Revoke, then type the token's name to confirm
Revoking takes effect immediately — any tool still using the token will receive an authorisation error. Revoke tokens as soon as they are no longer needed, or if you suspect a token has been exposed.