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. When using command-line tools like cURL, enter your API key with the -u or --username flag and append a colon to the end. Most HTTP clients and API testing tools (like Postman) will handle this formatting automatically.

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.

API_KEY='apiKeySecretValue'

Authentication using Basic Auth

To authenticate using the basic auth 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.

📘
Using Postman?
For detailed instructions on using API keys with Postman, including automatic base64 encoding, see Use Your API Credentials with Postman.

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:

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.
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 within application code

To use your API key within an application context, you must provide it as a Base64-encoded value via the Authorization header. Add a trailing colon (:) to the end of your key before encoding.

👉
Most libraries handle encoding automatically
When using HTTP client libraries in most programming languages, you can typically provide the API key and let the library handle the Base64 encoding. The examples below show both approaches.

JavaScript example (automatic encoding)

Most modern HTTP clients handle Basic Auth encoding automatically:

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', {
      auth: {
        username: API_KEY,
        password: ''
      }
    });
    assert.deepEqual(result.data, { info: 'pong', status: 1 });
    console.log(result.data);
  } catch(e) {
    console.error(e);
  }
})();

JavaScript example (manual encoding)

If your HTTP client doesn't support automatic Basic Auth encoding, you can encode manually:

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.data, { info: 'pong', status: 1 });
    console.log(result.data);
  } catch(e) {
    console.error(e);
  }
})();

Call Ping (using API Key)

Open Recipe

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