About using Postman with Shipium APIs

Postman is a popular API testing tool that makes it easy to test and develop API integrations. This guide walks you through configuring Postman to work with the Shipium API using both authentication methods:

• API key authentication. Uses Postman's Basic Auth helper
• OAuth 2.0 authentication. Uses Postman's OAuth 2.0 helper with automatic token management

Postman handles credential encoding automatically, so you don't need to manually base64-encode your credentials.

Prerequisites

• You must already have created either an API key or OAuth 2.0 credentials. You can find instructions for doing so in Create API Credentials.
• You must have installed Postman.
• You should have your API key or OAuth credentials ready.

Set up your Postman environment

👉

What is an environment in Postman?

An environment is a set of variables you can use in your Postman requests. Using environments makes it easy to switch between different API credentials or environments (test vs. production).

For more information, see Managing Environments in the Postman user guide.

Create a new environment

To create a new environment in the Postman application:

1. Click Environments on the left sidebar.
2. Click the + plus button to create a new environment.
3. Enter a name for your environment (e.g., "Shipium Production" or "Shipium Test").
4. Add variables based on your authentication method (see sections below).
5. Click Save.

Variables for API key authentication

If you're using API key authentication, create these variables:

Variables for OAuth 2.0 authentication

If you're using OAuth 2.0 authentication, create these variables:

📘

Postman data entry requirement

Postman requires you to enter initial and current values for environment variables. By default, Postman will automatically copy the initial value into the current value field.

API key authentication in Postman

Postman's Basic Auth helper makes API key authentication simple by automatically handling the base64 encoding for you.

Configure Basic Auth for API keys

1. Create a new request or select an existing one.
2. Click the Authorization tab.
3. From the Type dropdown, select Basic Auth.
4. Enter the following:
   1. Username: {{API_KEY}}
   2. Password: Leave this field blank.
5. Postman will automatically encode your credentials and add the correct Authorization: Basic header.

Test with the ping API

You can verify your setup by calling the ping API:

1. Create a new request in Postman.
2. Set the request method to GET.
3. Enter the URL: {{RESOURCE_SERVER}}/api/v1/deliveryexperience/ping
4. Configure Basic Auth as described above.
5. Select your environment from the environment dropdown (top right corner).
6. Click Send.

The ping API should respond with JSON that resembles this:

{
  "info": "pong",
  "status": 1
}

👍

Use this pattern for all API calls

Once you've configured authorization, you can use this same setup for all Shipium API endpoints. Simply change the URL and request method as needed for different API calls.

OAuth 2.0 authentication in Postman

Postman's OAuth 2.0 helper automates the token retrieval process and can even refresh tokens automatically when they expire.

Configure OAuth 2.0

1. Create a new request or select an existing one.
2. Click the Authorization tab.
3. From the Type dropdown, select OAuth 2.0.
4. On the right side, under Configure New Token, enter the following:
   1. Token Name: Shipium OAuth Token (or any descriptive name)
   2. Grant Type: Select Client Credentials.
   3. Access Token URL: {{TOKEN_URL}}
   4. Client ID: {{CLIENT_ID}}
   5. Client Secret: {{CLIENT_SECRET}}
   6. Client Authentication: Select Send as Basic Auth header.

Get your access token

1. Click the Get New Access Token button at the bottom of the configuration section.
2. Postman will make a request to Shipium's OAuth server and retrieve an access token.
3. A dialog will appear showing your new token details.
4. Click Use Token to apply it to your request.

Postman will automatically add the token to your request's Authorization: Bearer header.

Test with the ping API

1. vWith your token configured, enter the URL: {{RESOURCE_SERVER}}/api/v1/deliveryexperience/ping
2. Set the request method to GET.
3. Select your environment from the environment dropdown.
4. Click Send.

The ping API should respond with:

{
  "info": "pong",
  "status": 1
}

Manage token expiration

OAuth 2.0 access tokens expire after a certain time (shown in the expires_in field of the token response). When your token expires:

1. Go back to the Authorization tab.
2. Click Get New Access Token again.
3. Click Use Token to apply the new token.

👉

Automatic token refresh

Some versions of Postman can automatically refresh expired tokens. Check your Postman version's documentation for this feature.

Troubleshooting

Common mistakes

❌ Using OAuth 2.0 type for API keys If you're using an API key, select Basic Auth as the authorization type, not OAuth 2.0. The OAuth 2.0 type is only for OAuth 2.0 credentials.

❌ Forgetting to select your environment Make sure you've selected the correct environment from the dropdown in the top right corner of Postman. Your variables won't populate if no environment is selected.

❌ Including password with API Key When using Basic Auth with an API key, leave the password field blank. Only enter your API key in the username field.

Token errors

If you receive an invalid_token error when using OAuth 2.0:

• Verify that your Client ID and Client Secret are correct in your environment variables.
• Check that you've clicked "Use Token" after retrieving a new token.
• Ensure the token hasn't expired. Generate a new token if needed.

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support