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.
- Name your new API token.
- 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:
Request HTTP Headers | Required for | Description |
---|---|---|
X-Oneflow-API-Token | All endpoints | API access token. |
X-Oneflow-User-Email | Some endpoints | The email address of a registered Oneflow user who belongs to the same account as the API token. You can find all user-related information using the Get users in an account endpoint. |
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.
Updated over 2 years ago