API Key-Based Authentication

Set up your organization's API keys to connect with our APIs.

About API key-based authentication

Shipium supports the use of application programming interface (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.

Managing 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. See Creating 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.
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 client uniform resource locator (cURL) or via the Authorization tab in Postman or similar tools. Postman is an API platform for building, testing, and using APIs.

Testing using the ping API

πŸ‘

Validating 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 JSON object with a status=1 and info="pong".

To test:

  1. Replace <API_KEY> below with the API Key that you retrieved earlier, and keep the RESOURCE_SERVER as shown in the example below.
  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 this:

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

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

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

πŸ“˜

More information on the API responses

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