Make your first API calls with Postman

1. Ensure the X3 user that will be used for your pairing request has the correct security profile.

   Go to Administration > Users > Security profiles, and on the ‘thirdParties’ line ensure that ‘Create’, ‘Read’ and ‘Write’ are checked.

   

   Ensure that your registered app has the right value for callback URL to use Postman: https://getpostman.com/oauth2/callback

2. Import Postman collection for API calls

   Using Postman, you can create your first request to the X3 API. The requests used in this Quick Start Guide are available as a Postman collection. Click Run in Postman to load the collection into Postman. We recommend using the Postman desktop app.

   

   Or, manually import the Postman collection

   • Download the Postman collection for X3 Endpoints here.

   • Open Postman and click Import.

   • Select the downloaded Postman Collection file.

   • The Collection are now ready to use in Postman.

3. Edit the imported collection, in Authorization tab, choose OAuth2, then click “Get New Access Token”:

   Please note, Postman does not handle the regional API Gateway handover information as described in the customer approval step in OAuth2. So, ensure the regional API endpoint associated to the customer X3 configuration is correct in the form (Auth URL and Access Token URL).

   

   Postman browser will open X3 customer url for login:

   

4. The browser will direct the X3 user to the pending application approval with scope page. They can then accept or reject the request.

   

5. To accept the request, the X3 user must select which folder(s) the App can access. See FAQs for more about folders.

   

6. If the request is accepted, Postman is notified by callback and convert authorization code into tokens – for example:

   

   Then click on Use Token and save your collection

7. Make your API calls!

   For example, to get a list of all available X3 folders (In Auth tab, please choose Type = “Inherit auth from parent”):

   

8. Upload a file to an X3 configuration

   • Requirements for this step:

     • Url of API to call as described in step 3 of this page

     • A valid access token for this endpoint obtained as shown in the previous step 6

   • This functionality has 2 steps:

     • Obtain a signed upload url

       

     • Upload the file using the presigned URL obtained previously

       

The access token lasts only 5 minutes so, in case of token validity expiration, you should restart from step 4 in order to get new access token.

To take further advantage of this useful Postman, we have a special section “Postman” where we share our best practices and scripts to deal even more easier with our API protected by OAuth2 framework.