API Key-based Authentication

Overview

Shipium supports the use of API keys to authorize requests.

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

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

  • Use the Basic Auth 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 API keys

Administrators can create and deactivate API keys by using the Shipium partner console.

Prerequisites

  • You must already have created an API key. See Creating API Credentials.
  • As you go through this guide, you will run some basic API calls so must have your API Key ready and available. To make things easier, we recommend putting it into a local environment variable in your shell as shown below. In some cases, you will 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 cURL or via the Authorization tab in Postman or similar tools.

Testing using the ping API

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.


Did this page help you?