# About using Postman with Shipium APIs

[Postman](https://www.postman.com/) 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](https://docs.shipium.com/docs/creating-api-credentials).
- You must have installed [Postman](https://www.postman.com/downloads/).
- 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](https://learning.postman.com/docs/sending-requests/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:

| Variable name   | Initial value                        | Description                        |
| ---------------- | ----------------------------------- | --------------------------------- |
| `API_KEY`       | Your API key from Shipium Console   | The API key secret value          |
| `RESOURCE_SERVER`| `https://api.shipium.com`          | The Shipium API base URL          |

## Variables for OAuth 2.0 authentication

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

| Variable name   | Initial value                      | Description                       |
| ---------------- | --------------------------------- | -------------------------------- |
| `CLIENT_ID`     | Your OAuth Client ID              | From Shipium Console              |
| `CLIENT_SECRET` | Your OAuth Client Secret          | From Shipium Console              |
| `TOKEN_URL`     | `<https://auth.shipium.com/oauth/token>` | OAuth token endpoint      |
| `RESOURCE_SERVER`| `https://api.shipium.com`        | The Shipium API base URL          |

# 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:

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

# 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. With 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:

```json
{
  "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.

# 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.

# Resources

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

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)

Updated 8 months ago