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.

Shell

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.

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

cURL

API_KEY='<API_KEY>'
RESOURCE_SERVER='https://api.shipium.com';

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:

JSON

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

JavaScript example (automatic encoding)

Most modern HTTP clients handle Basic Auth encoding automatically:

JavaScript

const axios = require('axios');
const assert = require('assert').strict;

const API_KEY = '<API_KEY>';

(async () => {
  try {
    const result = await axios('https://api.shipium.com/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:

JavaScript

const axios = require('axios');
const assert = require('assert').strict;

const API_KEY = '<API_KEY>';

(async () => {
  try {
    const result = await axios('https://api.shipium.com/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);
  }
})();

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

Recipe Title

Recipe Description

1{"success":true}