Tutorials

Create an application using Postman v6.1.3

Postman is a development software dedicated to APIs and easy to use. We advise you to try it in order to understand how Eliot APIs works. This tutorial will focus more especially on the OpenId Connect Standard (OIDC) based on Oauth2 authentication process which is mandatory to build your application

Important

You need to have already created a developer account to follow this step by step tutorial.

Also, you need to have subscribed to the Starter Kit and created your application. If it is not done yet, follow our Getting started and Create an application tutorials first.


Step 1 : Download and install


Step 2 : Launch

  • Once you have launched the program, click on “Request, create a basic request”
How to create a new request

 

  • Fill up the required fields and click on “Create collection” or choose an available collection
Name of the request and add to collection


Step 3 : Authorization flow

The first request you will need to send is a GET one for authorization:

https://partners-login.eliotbylegrand.com/authorize

 

 You will have to fill in 3 mandatory parameters in query string :

  • client_id : it’s the Application ID you received by email when your API was approved
  • response_type : value is “code”
  • redirect_uri : it is the “Reply Url” you specified at the creation of your API. You can recover it in your account at the “Details” section of your application. It must be EXACTLY the same (don’t forget the trailing slashes if specified). It corresponds to the page you want your end-users to be redirected to. For tests it can just be a placeholder : it doesn’t need to redirect to a true website

Other parameters are optional :

 

You can see below what your request must look like :

Parameters of the GET request

 

Nota

You can try different parameters by activating/deactivating them through a checkbox

 

Your GET request must look like this one :

Image of the GET request

 

Nota

If all of your parameters are correct, you will get a “Status: 200 OK”. If you receive an error code, please refer to the error code table

 

Now, open your internet browser and copy/paste the generated URL, then press “Enter”. (You possibly have to log yourself in one more time).

Finally, you will obtain a code to use in the next step to get the access_token.

Code obtained in the address bar


Step 4 : Collect your access tokens

Token’s goal is to keep confidential the transit and storage of information between the API and the end-user. It is mandatory to use tokens in the Oauth2 authentication process. The lifetime of a token is 3600 seconds (1 hour) and a refresh token is 7776000 seconds (90 days). Let’s see how to collect them.

 

Go back to Postman and click on the “+New” button in the upper left corner.

Button for the creation of a new request

 

Create a new Request like you did on “Step 2 : Launch”.

This time, choose “POST” method in the drop down menu.

Drop down menu for a POST request

 

This request is a POST one for the token generation:

https://partners-login.eliotbylegrand.com/token

 

You will have to fill in 4 mandatory parameters in the body :

  • client_id : it is the Application ID you received by email when your API was approved
  • grant_type : value is authorization_code
  • code : it is the code you obtained in your web browser at the end of “Step 3 : Authorization flow”
  • client_secret : you received it by email at the approval of your application

 

Important

You absolutely need to keep the client_secret you received by email. It CANNOT BE SENT BACK TO YOU

 

You can see below what your request must look like:

Parameters of the POST request

 

In the “Authorization” tab and under “TYPE”, choose “OAuth 2.0” in the drop down menu.

Choice of the Oauth2 protocol in the drop down list

 

Press “Send button”

Image of the Send button for the POST request

 

You are redirected to a sign-in popup. Just enter the login and password of your developer account.

Your developer account is also an end-user one. As a user, you need to give the permission to the API to access some kind of data. It must be accepted by the end-user in order to use the application.

User consent's popup (accept or deny)

 

Nota

If you update your application with new scopes, they will have to be reaccepted by the end-user.

 

Once the user consents accepted, you can access to your token’s information:

  • Access Token
  • Token Type
  • id_token and its expiration time
  • resource
  • refresh_token and its expiration time

 

Information displayed about the token code


Step 5 (optional) : Manually verify a token

You can check information contained in an id_token to be sure that he is valid.

  • Connect on jwt.io
  • Copy/paste the id_token that can be found in “Manage Access Token”
  • Choose the RS256 algorithm

 

Token's verification with an external tool

 

Nota

You can find here more documentation about the decoded information

 

Step 6 : Refresh_token flow

The refresh_token is used to obtain a renewed access token. Thanks to it, the user remain authenticated forever – he doesn’t have to log in at each connection

 

In Postman click on the “+New” button in the upper left corner.

Button for the creation of a new request

 

Create a new Request like you did on “Step 2 : Launch” and “Step 4 : Collect your access tokens”.

Choose “POST” method in the drop down menu.

Drop down menu for a POST request

 

This request is a POST one for the refresh_token generation:

https://partners-login.eliotbylegrand.com/token

 

You will have to fill in 4 mandatory parameters in the body :

  • client_id : it is the Application ID you received by email when your API was approved
  • grant_type : value is refresh_token
  • refresh_token : it is the refresh_token code you retrieved from the token flow described just before
  • client_secret : you received it by email at the approval of your application

 

You can see below what your request must look like :

POST request to obtain the refresh token


Step 7 (Optionnal) : Run your collection

Running your collection allows you to check if your requests worked and gives you an aggregate summary of what happened.

 

In the upper right corner of each 3 request you created, click on “Save” button.

Then, click on “Runner” in the upper left corner.

Image of the Runner button

 

Choose the collection containing your 3 requests in the list and click on “Run {YourCollectionName}”

Choice of the collection

 

The result must look like the following

Testing the run of a collection

 

A Status 200 OK means that the requests successfully worked.

 

Nota

If you get a ”400 Bad request” error in order of a “200 OK”, check your parameters. It can be caused by an incorrect code in the token flow or an incorrect refresh_token code in the refresh_token flow

 

You can also add scripts to your requests. In the following example, the script tells you if you received a 200 OK response or something else.

In each of your requests, click on “Tests” and copy/paste the following script

tests["status code is 200 : OK"] = responseCode.code === 200;