Overview 

If you want to work with the ONE DATA API or you want to call OD Microservice Processors (Input and Output) you need to authorize almost all of your requests with an "Authorization Token" (formerly "X-Auth-Token" / also called Bearer Token). It is used, as the name implies, to make sure that the user or program that makes the call has the necessary rights to do so. Usually, it looks like that:

"Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzZWJhc3RpYW4uZ29tYm9jekB5kZSIs1dGhvcml0a..."

In the standard configuration it is valid for 24h after its creation (i.e. login). With the token one can do everything that the user, whose credentials were used, can do on the instance. So every request that contains the token will have the respective user information attached as well.

At the moment, a logout, by API Call or User Interface, does not invalidate the token, meaning you should be careful whom you give access to the token and where you save it.

In general, there are several ways to retrieve the token, not only for OD, but for every other service that uses this form of authentication. The following sections will explain how to do so in different ways, but you will achieve the same token in the end.

Via Browser Developer Tools

Using the integrated DevTools of your browser is a relatively easy way to get the token. To open them, just press F12, or right click in the browser window and click "Inspect" / "Inspect Element".

In this tutorial, we will use the Chrome / Chromium (Linux) browser. If you use a different browser, your User Interface may differ a little from the pictures in this article, but the procedure is similar.

There are two different ways to retrieve the token with the DevTools. If you are already logged in to your OD instance, go for the following section, if not, the second method may be faster for you.

Get the token from the browsers "localstorage"

First, open the DevTools on any ONE DATA page. Then follow the steps form the following video to access your browsers localstorage, where the token is saved.

In Firefox for example, the tab is called "Storage" and not "Application"

Once you found the local storage in your browser, you are able to click the ONE DATA URL to see the information saved there. It should look something like this:

The Bearer Token is the value of the "authToken" property of the shown JSON object.

Note that if you want to use the token retrieved above, you need to put "Bearer" in front of the token value, so it looks like the example token in the Overview section!

Get the token from the "Network" tab

1. First, go to the ONE DATA login screen and open the DevTools there
2. Login with your credentials (it is important that you open the tools before you log in)
   
3. Switch to the "Network" tab in the DevTools, the you will find a list of all requests made to the OD server
   
4. Click on (almost) any request. There you will find a section called "Request Headers", where you can find your current authorization token.

Via .../api/v1/users/login

Another way to get a token is via the Login call. This requires that a valid Username and Password are sent to the ONE DATA instance. Meaning if you want to reuse this procedure (e.g. full automation of Workflows that use the API), you would need to save this information somehow. Most of the times using a technical user with only the minimal needed permissions for the task is better than a real user.

The picture below, shows how to call the endpoint using Postman:

We need to make a POST request to the following URL:

"[OD_instance_URL]/api/v1/users/login"

If the request was successful, you will find the authorization token in the response headers.