API tokens

API tokens allow your integration prove its identity when it calls the SafetyCulture API. Every request runs as the token owner (a user or a service user), so the token also determines what data your integration can access and what actions it can perform.

Keep tokens safe

Store tokens in a secrets manager or encrypted vault. Do not commit tokens to source control or paste them into public tickets.
Create separate tokens per environment (development, staging, production) so you can rotate or revoke without disrupting everything.
Give the token owner only the permissions and access that the integration needs.
Rotate tokens on a schedule, and rotate immediately if you suspect exposure.
Revoke tokens you no longer use, especially after tests or partner handoffs.

1. Choose a token type

SafetyCulture supports two token types. Choose the token type that matches how you plan to run the integration.

Service user API tokens	User API tokens
Choose this option for shared integrations and long-running automations.	Choose this option for personal workflows where access should mirror a specific user.
You create the token for a service user and assign permission sets to that service user.	The token belongs to an individual user and inherits that user’s permission set.
User changes do not affect the token’s stability.	The token can stop working if the user leaves the organization or loses access.
The service user cannot log in to the app.	The token owner can log in to the app.

What data can API requests access with API tokens?

API requests run as the token owner (user or service user). The API will only return or change data that the token owner can access in SafetyCulture. The API evaluates:

Permissions, which control what actions requests can perform.
Access, which controls which items requests can return or work with based on sharing rules, group and site membership, and other access rules.

If content exists in SafetyCulture but does not appear in your API responses, validate the token owner’s access to that content.

📘
If you belong to multiple organizations, you need to create separate API tokens for your integrations.

2. Create API tokens

Service user API tokens

Each organization can have up to 20 active service user tokens.

🚧
If you're using a service user API token for SCIM provisioning, the service user must have both "Platform management: Users" permission and "Platform management: Groups" permission.

Requirements

Create a service user API token

Log in to the web app.
Click your organization name on the lower-left corner of the page and select Integrations.
Select API tokens from the tab at the top of the page.
Click + Create API token on the upper-right of the page.
Complete the following details:
- Enter a name for the service user API token to describe its purpose.
- Choose how long the token remains active before it expires due to inactivity. You can select 31, 45 (default), 60, or 180 days.
- Select the permission sets for the service user. All permissions are selected by default.
Click Create token on the lower-right of the page.
In the pop-up window, click the service user API token to copy it. Save the token securely before closing the window.

📘
Manage your service user API tokens regularly to securely connect external systems.

User API token

Each user can create up to 10 active user API tokens.

Requirements

Create a user API token

Log in to the web app.
Click your username on the lower-left corner of the page and select My Profile.
Click Settings on the upper-right of the page.
Select API tokens on the upper-right of the page.
Click Generate API token.
In the pop-up window, enter a user API token name and your account's password.
Click Generate.
Click the user API token to copy it. Save the token securely before closing the window.

📘
Manage your user API tokens regularly. User API tokens expire after 30 days of inactivity. Expired tokens will stop your integrations from working until you generate a new one.