About API key-based authentication

Shipium supports the use of API keys to authorize requests to connect with our APIs.

API keys are persistent and remain valid until deactivated. This is different from using OAuth 2.0, where access tokens must be refreshed periodically.

Use your organization's API key by providing it in the header of the API call:

• Use the Basic Auth Hypertext Transfer Protocol (HTTP) header.
• Use the Basic Auth username value when providing your API key.
• Do not specify a password.

👉

Basic Auth formatting

Basic Auth uses a colon to separate username and password.

Enter your API key with the -u or --username flag and append a colon to the end.

Manage your API keys

Administrators can create and deactivate API keys within the Shipium Console. Members of your organization without administrator permission cannot manage your API keys.

Prerequisites

• You must already have created an API key. You can find instructions for doing so in Create API Credentials.
• You must have your API key ready and available to make basic API calls as you go through this guide. To simplify the process, we recommend putting your API key into a local environment variable in your shell as shown below. In some cases, you'll pass it as a Base64-encoded value, which we will also put into an environment variable. You can Base64 encode your API key with a client uniform resource locator (cURL) command.

API_KEY='apiKeySecretValue'

Authentication using Basic Auth

To authenticate using the bearer token mechanism, include --user "$API_KEY:" as part of your API calls. You can do this by using cURL or via the Authorization tab in Postman or similar tools. Postman is an API platform for building, testing, and using APIs.

Test using the ping API

👍

Validate API access

Start by confirming that you can access the APIs by calling the ping API to validate that things are working correctly.

The ping API primarily exists so that you can debug your programmatic connection to Shipium servers during testing and integration. It always returns back a JavaScript Object Notation (JSON) object with a status=1 and info="pong".

To test:

1. Replace <API_KEY> in the first line below with the API key that you retrieved earlier, and keep the RESOURCE_SERVER as shown in this example.
2. Make the cURL request shown below.

API_KEY='<API_KEY>'
RESOURCE_SERVER='<<api_url>>';

 curl --location --request GET "$RESOURCE_SERVER/api/v1/deliveryexperience/ping" \
   --user "$API_KEY:"

The ping API should respond with JSON that resembles the following example:

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

Use the Base64-encoded value

To use your API key within an application context, you must provide it as a Base64-encoded value via the Authorization header. To do this, add a trailing colon (:) to the end of your key. You'll use the Base64-encoded value as the BASIC_AUTH_TOKEN in a Basic Auth header when calling Shipium's APIs.

Note: As with the cURL example, no password is required.

Here's a JavaScript example:

const axios = require('axios');
const assert = require('assert').strict;
const API_KEY = '<API_KEY>';

(async () => {
  try {
    const result = await axios('<<api_url>>/api/v1/deliveryexperience/ping', {
      headers: {
        Authorization: `Basic ${Buffer.from(API_KEY + ':').toString('base64')}`
      }
    });
    assert.deepEqual(result, { info: 'pong', status: 1 });
    console.log(result);
  } catch(e) {
    console.error(e);
  }
})();

👍

Use this pattern for all API calls

The example above for ping applies to all API key access of Shipium's APIs.

📘

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