There are two ways to make API requests with user-level permissions in Oneflow. You can use a personal access token that belongs to a specific user, or make a request with a regular API token on behalf of a user.
Use a personal access token
A personal access token is connected to the user who created it. Requests made with the token are automatically limited to the workspaces, templates, contracts, and other resources available to that user.
Use a personal access token when an integration should always operate with one user's permissions. This is particularly useful for MCP connections, development, testing, and exploratory API use.
Unlike a regular API token, a personal access token does not provide broad account-level access and does not require you to identify a user separately for authorization.
Make a regular API request on behalf of a user
A regular API token provides access to the Oneflow account associated with it. The token itself cannot be scoped to a particular user.
For supported requests, you can include a user's email address in the X-Oneflow-User-Email header. Oneflow will then authorize that request according to the identified user's permissions.
Note: Adding the user email does not change or restrict the regular API token itself. It only applies the user's permissions when Oneflow authorizes the individual request.
Headers for regular API tokens
When authenticating with a regular API token, the following HTTP headers are used:
-
X-Oneflow-API-Token
Contains the regular API token associated with your Oneflow account. It is required for all endpoints. -
X-Oneflow-User-Email
Contains the email address of an active Oneflow user in the same account. Oneflow uses the identified user's permissions when authorizing supported requests.
Submitting the user's email is required for correct authorization for most create and update requests. You can retrieve the users in an account with the Get users in an account endpoint.
How does user-based authorization work?
Imagine that a user named John does not have permission to access a particular contract.
If John's email address is included in the X-Oneflow-User-Email header of a Get a contract request, the request will fail. Oneflow evaluates the request using John's permissions, and John is not allowed to access that contract.
What happens if I don't include a user email?
A request made with a regular API token and without the X-Oneflow-User-Email header is authenticated and authorized as an anonymous admin user request. User-specific permissions are therefore not applied.
If an integration should consistently be restricted to a specific user's access, use a personal access token instead.
Which option should I use?
| Personal access token | Regular API token with a user email |
|---|---|
| Inherently connected to the user who created it. | Connected to the Oneflow account. |
| Always operates within its owner's permissions. | Applies user permissions to requests that identify a user. |
| Does not require a separate user email for authorization. | Uses X-Oneflow-User-Email to identify the user. |
| Recommended when an integration should act as one specific user. | Suitable when an account-level integration needs to make requests on behalf of different users. |
For technical information about regular API authentication, see the authentication and authorization documentation.