Introduction
A Personal API Token lets an AI assistant, or another tool, work with your ComplyFlow data on your behalf. You need one for Claude Code, Claude Desktop, GitHub Copilot in VS Code and the ChatGPT desktop app.
If your AI app lets you sign in to ComplyFlow instead, you don't need a token. Refer to Signing in with an AI app or using a Personal API Token.
You need the MCP / API token access permission, or Edit Organisation Details. If API Tokens isn't in your profile menu, ask your ComplyFlow administrator. Refer to Giving Staff Access to AI Assistants
Create a token
1. Select your name or picture at the top right to open your profile menu, then select API Tokens. The Personal API Tokens page opens.
2. Select New token. If you don't have any tokens yet, select Create your first token.
3. In New API token, enter a Name that reminds you what it's for, for example Claude Code – Safety reports.
4. Under Scopes, tick what the token is allowed to do. Refer to Choosing scopes below.
5. Under Expires in, choose how long the token lasts: 7 days, 30 days, 60 days, 90 days, 1 year or Custom… (a date up to one year away). The default is 30 days.
6. Select Create token.
7. Select the Copy button next to Token. The token starts with cf_pat_. The second Copy button, next to Use as, copies the whole Authorization: Bearer cf_pat_… line instead. Use that only where a guide asks for the full header.
8. Store it somewhere safe, such as a password manager, then select I've copied my token — close.
Your token is shown only once. ComplyFlow can't show it to you again. If you lose it, revoke it and create a new one.
Choosing scopes
Scopes control what the token can do. Each one is either read (look things up) or write (make changes).
Read scopes
Scope | Lets the token read |
Sites & projects | Sites, projects, site configuration, site documents and site sign-ins |
Staff | Staff, their training and documents |
Contractors | Supplier companies and their documents, and workers' training records. Doesn't include other worker details |
Workers | Workers, their details and documents |
Incidents | Incident reports and incident questions |
Inspections | Inspections, actions, templates and corrective actions |
Plant & equipment | Plant items and their categories |
Risk register | Risk register entries and activities |
Forms & permits | Forms and permit submissions |
Write scopes
Write scopes only work once write access has been turned on for your organisation. Write access is available on request, so contact ComplyFlow support to ask for it.
Until then, a token with write scopes can still read, but it can't make changes.
Scope | Lets the token |
Sites & projects (write) | Create and update sites, assign suppliers and staff, upload site documents |
Staff (write) | Add, update, activate and deactivate staff, and manage their permissions, competencies and notes |
Suppliers (write) | Invite and update suppliers, change their categories and sites, and add or remove additional document requirements |
Workers (write) | Update workers and their documents |
Incidents (write) | Report incidents, add corrective actions and investigations, and sign off |
Inspections (write) | Create and schedule inspections, record findings and close actions |
Plant & equipment (write) | Add, update and reactivate plant items |
Risk register (write) | Create risks and add controls |
Forms & permits (write) | Create and approve permits, and complete and submit forms. Checkbox and radio-button questions can't be answered this way yet |
Training (write) | Assign online and offline training and record completions |
Work orders (write) | Not used yet. You don't need to tick it |
Tips
Tick only what you need. For reports, read scopes are enough. Add write scopes only when you want the assistant to make changes and write access has been turned on for your organisation. Refer to Making changes in ComplyFlow with an AI assistant.
Select all ticks write scopes too. Check the list before you create the token.
Documents, training and sign-ins don't have their own read scope. Supplier documents and workers' training records come with Contractors, site documents and site sign-ins with Sites & projects, and staff documents and training with Staff.
Greyed-out scopes are ones your own permissions don't allow. The reason is shown underneath, for example "You don't have Workers Read/Write — a token can't use this scope." Ask your administrator if you need it.
Incidents greyed out? If the reason says "Incident module is not enabled for this account", your organisation doesn't use the Incident module.
Scopes don't change after you create a token. If your permissions change, create a new token.
Your token never does more than you can
A token is always limited by your own access:
Your permissions: if you can't view or change something in ComplyFlow, nor can the token, even if the scope is ticked.
Your sites: if you only have access to some sites, the token only sees those sites.
Your organisation: a token only works in the organisation you created it in.
To check which organisation and scopes a token has, ask your assistant: "Using ComplyFlow, who am I and what can I access?" The answer lists the scopes that work right now: the ones ticked on the token that your permissions still allow. If a scope you ticked is missing from the list, your permission for it has been removed, so ask your administrator. If you have access to every site, it may say you have 0 allowed sites. That's expected: the number only counts sites you've been assigned to.
Managing your tokens
The Personal API Tokens page lists your tokens with their Name, Scopes, Last used and Expires.
Hover over the scope count to see which scopes a token has.
The Expires label turns yellow in the last 7 days and red when the token has expired. Expired tokens stop working and can't be extended, so create a new one.
You can have up to 10 active tokens at a time. Revoke one you no longer use to make room.
Revoke a token
1. On Personal API Tokens, select Revoke next to the token.
2. Type the token's name to confirm, then select Revoke token.
The token stops working straight away. Revoke a token as soon as you stop using it, or if you think someone else has seen it.
Connected apps
If you've connected an AI app by signing in, it's listed under Connected apps on the same page. That section only appears once you've connected an app. Refer to Signing in with an AI app or using a Personal API Token.