Token authentication#
Danger
(Refresh-)token authentication is discouraged. See API-key authentication for the recommended authentication method. This document is meant as a maintenance reference for pre-existing client implementations.
How it works#
After you finished the account setup, you can use your credentials (username and password) to
obtain an initial access_token+refresh_token-pair via the /token endpoint (see:
Password Grant Flow).
The access_token serves as an authentication for other endpoints. For security reasons it has a short time-to-live
and needs to be refreshed regularly. This should be done by submitting the refresh-token
to the same /token endpoint (see: Refresh Token Grant Flow, which will yield a fresh
access_token+refresh_token-pair without the need to re-submit username and password.
Note
We recently introduced reuse-detection as an additional security feature to the Refresh Token Grant Flow.
In practice this means, that each refresh-token can only be used at most once. If a token-reuse is detected
the login-session will be invalidated, i.e. all related access-tokens will be logged out to mitigate
token-stealing scenarios.
Caution
Everyone with access to the refresh token could use it to obtain the next access-/refresh-token pair and use natif.ai APIs on behalf of your organization. It should thus generally be handled with the same care as other login credentials.
Password grant flow#
To obtain the initial token pair with your username and password, the API offers the OAuth 2 password grant flow.
You just need to do an HTTP POST request with grant_type set to password and the username and password
in the payload of the POST request.
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
class Main {
public static void main(String[] args) throws IOException {
URL url = new URL("https://api.natif.ai/token?realm=public");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST");
httpConn.setRequestProperty("accept", "application/json");
httpConn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
httpConn.setDoOutput(true);
OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
writer.write("grant_type=password&username=username&password=password&refresh_token=&scope=capturing_read%20capturing_write");
writer.flush();
writer.close();
httpConn.getOutputStream().close();
InputStream responseStream = httpConn.getResponseCode() / 100 == 2
? httpConn.getInputStream()
: httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
}
}
Once submitted you will receive the following response from the API:
{
"access_token": "eyJh...1Sa4ov-ZSYQ",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "eyJh...uHr9VRug",
"token_type": "bearer",
"scope": "capturing_write history"
}
The returned access_token can now be used to authenticate your API requests.
Refresh token grant flow#
The returned refresh token can be used to get a new access token upon expiration without the need to re-enter your credentials.
Info
Make sure to keep your refresh token safe, and to monitor its expiration date.
You just need to do an HTTP POST request with grant_type set to refresh_token and the refresh token in the payload
of the POST request.
Authenticate your API calls#
You can now authenticate your API requests by adding the access_token to the header of it.
import requests
headers = {
'accept': 'application/json',
'Authorization': 'Bearer <access_token>'
'Content-Type': 'multipart/form-data',
}
files = {
'file': ('invoice.jpg;type', open('invoice.jpg;type', 'rb')),
}
response = requests.post('https://api.natif.ai/documents/', headers=headers, params=params, files=files)
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
class Main {
public static void main(String[] args) throws IOException {
URL url = new URL("https://api.natif.ai/documents/");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("POST");
httpConn.setRequestProperty("accept", "application/json");
httpConn.setRequestProperty("Authorization", "Bearer <access_token>");
httpConn.setRequestProperty("Content-Type", "multipart/form-data");
InputStream responseStream = httpConn.getResponseCode() / 100 == 2
? httpConn.getInputStream()
: httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
}
Privileges & Scopes#
If you use the password grant flow, you can define exactly which scopes & privileges you want to have. The following four scopes are available:
capturing_write- Allows for submitting documents for processing.capturing_read- Allows read access for submitted documents and their processing results.postprocessing- Allows read-write access to document postprocessing.user_management- Allows read-write access to user management functionality.
You can pass scopes in the /token request by setting the scope attribute as a request parameter. The value of the
attribute field is a string with the corresponding scopes separated by a whitespace.
The default value is "capturing_read capturing_write"