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

1. Log in to Oneflow.

2. Go to the Marketplace and click on API tokens. This should already be enabled if your plan supports it.

   

3. Click on + Generate a new token

   

4. Enter a name for the API token and click Confirm.

   

5. Copy and store the API token in a secure location 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 an API token, go to the Marketplace > API tokens > click on the Actions menu next to the token and select Revoke.

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.