Set up Postman to use the Socotra API

This article explains how to set up Postman to use the Socotra API.

Overview

The Socotra API provides a programmatic approach to exercising and building on top of the Socotra platform. All Socotra operations are available via a series of HTTP endpoints.

Postman is an API testing tool that makes it easy and accessible to test and familiarize yourself with how the Socotra API works.

What will I learn?

By the end of this guide, you will know how to:

• Import a sample Socotra Postman collection and Socotra Postman environment.

• Edit your environment variables to authenticate against the Socotra API.

• Authenticate against the Socotra API.

What will I need?

You will need the following:

• A copy of the Socotra Sample Collection and Environment

• Credentials for logging into Socotra

To authenticate with the Socotra API, you’ll need a set of credentials for logging into your business account.

To gain access to a Socotra Insurance Suite business account with user credentials, navigate to https://www.socotra.com/contact-us/ and fill out the form to speak to a Sales representative and book a demo.

Alternatively, you can reach out by sending an email to sales@socotra.com.

Issues with your credentials?

If you’ve already reached out to Socotra, received credentials, but can no longer find them, or you’re having issues using the credentials, reach out to your Socotra representative for assistance.

Ready to begin?

Continue onto the next section to learn how to set up Postman to use the Socotra API.

Steps

Part 1 - Set up your collection and environment

To get started making requests against the Socotra API, you’ll first need to import the Socotra Postman collection. The collection contains preformed requests that make it easier for you to test the API.

You’ll also need to import an environment, which is where you’ll input your credentials for authenticating against the API.

1. Navigate to https://postman.com.

2. Log into your Postman account.

   1. If you don’t have a Postman account, register for one and log in.

3. Once you’ve logged into Postman, you should see a screen similar to the one depicted in the screenshot below.

4. In the left sidebar, click Import.

5. Upload the Socotra Postman collection you downloaded in the What will I need section above?

6. After importing the collection, it should appear in the left sidebar.

7. After importing the Postman collection, the next step is to import the Postman environment.

8. In the left sidebar, click Environments. Then, click Import.

9. Upload the Socotra Postman environment you downloaded in the What will I need? section above.

10. After importing the environment, it should appear in the left sidebar.

Part 2 - Set up your environment

With the Socotra Postman collection and environment imported to your workspace, the next step is to update the environment with your authentication credentials.

The Postman environment is a convenient way of storing all of the data necessary for connecting with the Socotra API. In this part, we’ll walk through how to set up authentication so you can use the Socotra API.

1. In the left sidebar, click Environments.

2. Open the Socotra Sample Environment environment.

3. You should see a screen similar to the one depicted in the screenshot below.

The variables defined in the Socotra Sample Environment are used throughout the Socotra Sample Collection. Some of the variables are used for authentication so that you can use the API. Other variables are used for storing data so that you can conveniently reference it when making API requests.

For right now, the three most important variables to cover are:

• business_account_name

• business_account_username

• business_account_password

As a reminder, this information is the same used when logging into the Socotra web app (for a refresher, see Log in to Socotra.

4. Type your credentials in the business_account_name, business_account_username, and business_account_password fields.

   1. Make sure to type the information in both the Initial value and Current value columns

   2. See the screenshot below for an example of how this might look.

5. Make sure that you save your changes. You can save in Postman by doing CTRL+S (Windows / Linux), CMD+S (Mac), or by pressing the Save button in the top-right corner of the screen.

With your three business environment variables inputted and saved, the next step is to get authentication from Socotra.

Part 3 - Authenticate with Socotra

With your environment variables updated, the final step is to authenticate against the Socotra API.

1. In the left sidebar, click Collections.

2. Click the Socotra Sample Collection collection.

3. Click the Authorization tab.

4. Scroll down the page. You may notice some fields that have values in curly braces that are red. Do not edit these values.

5. These values are referencing the variables established in the environment file. There is no environment selected, however.

6. In the top-right corner of the screen, click the No environment dropdown and select the environment called Socotra Sample Environment.

   1. This will tell Postman to use the variables declared in that environment.

7. Scroll down to the bottom of the page.

   1. Also, notice that the environment values are no longer red. This means that Postman is pointing to the environment file and populating the variables with the environment’s values.

8. Click Get New Access Token.

9. After clicking Get New Access Token, a dialog box should appear alerting you that your authentication was successful. Click Proceed or wait for the window to automatically redirect you.

10. A window will appear showing you an access token. Click Use Token.

11. Note that the access token expires five minutes after generation. Upon expiration, you’ll have to re-authenticate by refreshing the token.

Make a request to test your authentication

To make sure authentication was successful, you can run a simple endpoint of the Socotra API.

1. In the Socotra Sample Collection, navigate to Socotra Sample Collection > Auth > Users > Describe Current User (Who am I?)

   1. This is a very simple endpoint that returns basic information about the user making the API request, making it perfect for testing authentication.

2. Click Send.

3. If successful, you should receive a 200 OK code and a response body that looks something like the screenshot below:

4. If you receive 200 OK and a response body, congratulations! You’re ready to start using the Socotra API in Postman.

5. If you experience any issues, re-read this guide and check out the Troubleshooting section below.

Troubleshooting

If you’re receiving an “Authentication failed - Couldn’t complete authentication. Check the Postman Console for more details” message like the one depicted in the screenshot above, follow this checklist:

1. Make sure you’ve selected the correct environment. For this tutorial, you should have “Socotra Sample Environment” selected in the dropdown in the top-right corner of the screen.

2. Make sure that your business_account_name, business_account_username, and business_account_password environment fields contain your login credentials. Review Part 2: Set up your environment to review the steps to do this. Your configuration should look something like the screenshot below.

Recap

In this guide, we covered:

• How to import a sample Socotra collection and environment in Postman

• Edit an environment in Postman

• Get an access token for making requests to the Socotra API

Now that we have Postman set up, the next step is to explore the functionality that Socotra provides through its API.

Ready for the next module?

See Create an account to continue this learning path.