Authentication and authorization

Oneflow API uses an API token-based authentication. You will need to generate an access token in the Oneflow application and provide it as an HTTP header with every request. Sending an API token gives you access to the Oneflow account associated with the token.

Authorization and the second level of authentication are done by sending in the email address of an account user in a request header, which will allow for authentication checks based on user permissions. Submitting the user's email is required for correct authorization for most create or update requests.

Create an API token

Step 1. Enable the API tokens extension

To be able to generate an API token, you need to enable the API Token extension. To do this, go to Admin > Accounts > Extensions and toggle the API tokens extension:

Step 2. Generate an API token

When enabled, click the API tokens link and then click Generate a new token.

3. Name your new API token.

4. Copy the token and securely save it for future use.

📘

Note:

The token is shown only once.

Revoke an API token

If you believe that your API token is no longer secure, if it’s not used anymore, or if you want to disable a token for any other reason, you can at any time revoke an API token. Doing so will permanently remove the token from your account.

To revoke a custom API token, go to Admin > Account > Extensions > API tokens, select your custom API and click Revoke in the Actions menu.

Request headers

Authentication and authorization credentials need to be set for each request using HTTP headers.
There are two header parameters that you have to include in almost all of your API requests:

Requests made without the Oneflow user's email address will be authenticated and authorized as anonymous admin user requests. Setting the user email header allows you to leverage the permissions assigned to that user in Oneflow.

For example, user Sven has no permission to access a specific contract in Oneflow. If you include Sven's email address in the header of an API GET contract request, this request will fail.

📘

Note:

The email provided in the header must belong to an active Oneflow user.

curl --request GET \
  --url https://api.oneflow.com/v1/contracts/10015 \
  --header 'Accept: application/json' \
  --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
  --header 'x-oneflow-user-email: [email protected]'

import requests

headers = {
    'Accept': 'application/json',
    'x-oneflow-api-token': '9841f1ee533681c3ea6a438560f2bb6c73b76675',
    'x-oneflow-user-email': '[email protected]',
}

response = requests.get('https://api.oneflow.com/v1/contracts/10015', headers=headers)

This request will return the contract in JSON format.