Authentication and permissions

Send the token in the HTTP Authorization header on every API request:

Authorization: Bearer <your-token>

Use HTTPS and keep credentials out of URLs, logs and source control. There is no report-content or report-write scope.

Choose a token type

	Personal token	Organisation token
Prefix	ep_pat_	ep_oat_
Belongs to	You	One organisation
Created in	Account settings → Personal API tokens	Organisation → Organisation API tokens (administrators only)
Reaches	Every organisation you belong to, now and in future	Only its organisation
Report access	Your current role and case permissions in each organisation	Every report’s metadata in its organisation
When people leave	Stops for an organisation when your membership ends	Keeps working
Typical use	Your own scripts and account tasks, such as creating organisations	Shared automations, such as a Slack or dashboard integration

Use an organisation token for anything the organisation depends on. It does not break when the person who set it up changes role or leaves, and every administrator can see and revoke it.

Scopes

Each token carries fixed scopes chosen when it is created. Each operation in the API reference lists the scope it requires; a request without it returns 403 insufficient_scope, with a WWW-Authenticate header naming the missing scope.

Scope	Allows	Token types
reports:read	List and read report metadata	Both
channel:read	Read whistleblowing channel status	Both
channel:write	Read and change channel configuration. Organisation setup	Both
webhooks:read	List webhooks and their delivery history	Both
webhooks:write	Create, change, delete and test webhooks, rotate secrets and retry deliveries. Webhooks	Both
audit_log:read	Read the organisation’s and each report’s audit trail. Administration	Both
members:read	List members and pending invitations	Both
members:write	Invite members, resend and revoke invitations	Both
documents:read	List and download the channel’s documents	Both
billing:read	Read access and subscription status	Both
billing:write	Create subscription checkout and billing portal links	Both
organizations:write	Rename the organisation	Both
organizations:create	Create organisations	Personal only
invitations:respond	List, accept and decline your own invitations	Personal only

Product feedback needs no scope: any valid token can send it.

Read scopes are preselected; write scopes must be selected explicitly. Scopes cannot be changed after creation: issue a replacement token instead.

Case permissions

A personal token never does more than its owner could do in the web application. Every request rechecks current access. Administrators and viewers can read report metadata throughout their organisation. Members can read only reports assigned to them or in which they participate. Changing channel configuration, managing webhooks or invitations, listing invitations and renaming the organisation require a current administrator; reading the audit trail requires an administrator or viewer.

An organisation token has no role. Its scopes alone decide what it can do, and reports:read covers every report in the organisation, as an administrator’s view does. Only administrators can create one.

Which token can call each endpoint

Every operation in the API reference also lists the token types it accepts under Authorizations. A personal token additionally needs its user’s current role, shown in the last column.

Endpoints	Organisation token	Personal token
Discover organisations	Yes	Any user
Read channel metadata	Yes	Any member
List and read report metadata	Yes, every report	Administrators and viewers: every report. Members: reports assigned to them or in which they participate
Read and change channel configuration	Yes	Administrator
Webhooks and their deliveries	Yes	Administrator
Organisation audit trail	Yes	Administrator or viewer
A report’s audit trail	Yes	Access to that report
List members	Yes, including deactivated members	Any member. Only administrators also see deactivated members
List, send, resend and revoke invitations	Yes	Administrator
Rename the organisation	Yes	Administrator
List documents	Yes	Any member. Compliance evidence is listed only for administrators and viewers
Compliance report and certificate	Yes	Administrator or viewer
Policy, privacy notice, poster and case handler manual	Yes	Any member
Billing status, checkout and billing portal links	Yes	Administrator
Create an organisation	No	Any user with an active membership
List, accept and decline your own invitations	No	The invited user
Send product feedback	Yes	Any user

Required organisation agreements apply to both types. Personal tokens also require your current account terms. Organisation discovery can list an organisation whose agreement needs renewed acceptance; reading its report or channel metadata requires acceptance.

Tokens do not authenticate the web application. Open a report’s web_url in a separate authenticated browser session. Supplying a token alongside a browser cookie does not unlock confidential endpoints.

Expiry and replacement

Tokens expire after 90 days and cannot renew themselves. Generate a replacement, update the consuming system, verify it, then revoke the old token. Full credentials are displayed once when created. Each user, and each organisation, can have up to 20 unexpired, unrevoked API tokens. Revoke an unused token to free a slot.

Token activity

Token lists show Last used, or Never used if no activity has been recorded. Users see activity for their own tokens; organisation administrators see it for their organisation’s tokens.

Last used records a request that passed credential, request-shape, account-terms and token-rate checks. It can update even when access to the requested organisation or resource is denied.

Last successful request records a completed 2xx API response, including authorised setup writes, discovery and HEAD requests. Last refusal shows a timestamp and fixed diagnostic code for a request made with that credential. Unknown credentials never update another token’s diagnostics.

Refusal code	Meaning
expired / revoked	Replace the expired or revoked token
unavailable	The owner’s account, or the token’s organisation, can no longer be used
agreement_required	Accept the required user terms or organisation DPA in the web application
invalid_request	Review JSON body types, allowed fields, query, filters or pagination cursor
validation_failed	Correct the fields named in the validation error
rate_limited	Respect the response’s retry interval
insufficient_scope	The token lacks the scope the operation requires
forbidden	Current permissions do not allow the action
not_found	The resource is missing or inaccessible, or API access is suspended

Each timestamp updates at most once per minute independently. The code describes the refusal sampled at that timestamp; later refusals within that minute may have a different cause. These are operational hints, not a complete request history. Disallowed routes/formats and IP throttling before credential identification do not update them. HTTP errors continue to conceal whether an invalid credential is expired, revoked or unavailable.

Revocation

Users revoke their own personal tokens in account settings. Organisation administrators revoke organisation tokens on the organisation’s token page. An organisation stops a person’s personal tokens from reaching its data by ending that person’s membership.

Existing credentials remain available for revocation while API access is suspended. Closing an account removes its personal tokens; organisation tokens and webhooks stay with the organisation. Banned or closed accounts cannot authenticate.

Separate credentials

API tokens, webhook signing secrets, SCIM provisioning tokens and browser sessions serve different purposes. Never interchange them. OAuth access tokens exist only for the MCP server: they work at its endpoint, and the API refuses them.