How authentication works in Ermeo

The Ermeo API is based on a very common authentication system. In order to authenticate the requests sent to our API, a specific header is needed : Authorization.

The Authorization header value is what is called the access_token. Thus, each request sent to our API must contain this header with the correct access_token in order to access Ermeo data.

How to retrieve an access_token from your username and password

Routes used in this part:
Get access & refresh tokens

In order to retrieve the access_token that will have to be passed to the headers of each request sent to the API, a specific route exists:

POST https://api.ermeo.com/oauth/v2/token

This route will ask a specific body in order to return what is needed to identify your other requests (the access_token). Here is the body:

{
  "client_id": "client_id_given_to_you",
  "client_secret": "client_secret_given_to_you",
  "username": "your_username",
  "password": "your_password",
  "grant_type": "password"
}

The client_id and the client_secret will be given to you by the Ermeo team. This will allow us to know that you are sending the request from another source than our platform and our application.

The username and password are your usual credentials, the same used to access the platform and the application.

Finally, the grant_type corresponds to the type of authentication provided in the body. In this case, as you try to login with your username and your password, this must be set to password.

If you successfully sent this request, the API should return a response having the following body:

{
  "access_token": "your_access_token",
  "expires_in": 7200,
  "token_type": "bearer",
  "scope": "user",
  "refresh_token": "your_refresh_token"
}

Three things are important in this response. The access_token is the token generated that will be used to authenticate all the other requests. This token is valid for 2 hours from the time the authentication request has been sent (7200 seconds, the value corresponding to the expires_in key). After this period of time, you will have to send an authentication request again.

The refresh_token can also be very useful. It allows the generation of a new access_token without asking for the username and password again.

How to retrieve an access_token from a refresh_token

Routes used in this part:
Get access & refresh tokens

The refresh_token is a token valid for 2 weeks. It allows the generation of a new access_token without asking for the username and password again. Therefore, you don't need to store these confidential information (which is considered as a really bad practice and a security breach) as you can store this refresh_token instead. Here is how to use it to ask for another access_token when this one expires:

POST https://api.ermeo.com/oauth/v2/token

As you can see, the route is exactly the same as the one we used in the previous part. However, the body sent with this request is a bit different:

{
  "client_id": "client_id_given_to_you",
  "client_secret": "client_secret_given_to_you",
  "refresh_token": "your_refresh_token",
  "grant_type": "refresh_token"
}

The grant_type is now set to refresh_token, indicating to the API that you now try to generate a new access_token thanks to a refresh_token.

Instead of specifying a username and a password, you now have to pass to the body the refresh_token you retrieved from your previous authentication. The response from the API will be exactly the same as in the previous part:

{
  "access_token": "your_access_token",
  "expires_in": 7200,
  "token_type": "bearer",
  "scope": "user",
  "refresh_token": "your_refresh_token"
}

This response will give you a new access_token, valid for 2 hours and a new refresh_token, valid for 2 weeks. Please note that a refresh_token can only be used once.

Sending your first authenticated request

Routes used in this part:
Get access & refresh tokens
Get all assets

Now that you have everything you need to generate an access_token, let's dive into an example on how you can use it to send your first authenticated request. In this quick example, you will see how you can retrieve the list of all the assets of your workspace.

Let's start with sending a request to generate an access_token to authenticate our Get all assets request:

POST https://api.ermeo.com/oauth/v2/token

Example from Postman of a request to retrieve the access_token

As we can see from the response in the example, we now have in our possession an access_token:

NDg0YTBmNTYwN2JiNWM2Y2U1MWIzNjUyMDA2M2E0ZDRkNWZiMDA5NDgxYjliNjhlNTExYmU1ZDExNjA4Mjc5Mw

Thanks to this access_token, we are now able to ask the API to retrieve all the assets (a part of them actually, but we'll come to this later). We can send the following request:

GET https://api.ermeo.com/api/v1/assets

Let's try it!

Example from Postman of a request to retrieve all the assets without specifying the access_token

It didn't work, and that's normal. We are missing an important part of the request: asking for the access_token is not enough to automatically authenticate all the requests we make. We need to inform the API that we have the right to access the data we are looking for. The only way to do that is to specify a specific header to the request: Authorization, and pass the access_token preceded by "Bearer ". With our token, this would give:

Authorization: Bearer NDg0YTBmNTYwN2JiNWM2Y2U1MWIzNjUyMDA2M2E0ZDRkNWZiMDA5NDgxYjliNjhlNTExYmU1ZDExNjA4Mjc5Mw

Example from Postman of a request to retrieve all the assets specifying the Authorization header

As we can see, specifying this header allowed us to authenticate the request and get a response from the API. We are not going to go deeper in the explanations of the response of the API, we'll do that in another article. The main goal of this example was to demonstrate the steps to send an authenticated request.