1. 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.
2. 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:
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:
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 send this request, the API should return a response having the following body:
Three things are important in this response. The access_token is the generated token 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.
3. How to retrieve an access_token from a refresh_token ?
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:
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:
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.
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:
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: