About OAuth 2.0-based authentication

Shipium supports the use of OAuth 2.0 clients to authorize requests to connect with our APIs.

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

Use your organization's OAuth 2.0 client by providing it in the Authorization request header of the API call:

1. Retrieve an access token using /oauth/token.
2. OPTIONAL: Validate your access using ping.
3. Make calls to Shipium's APIs using the access token.
4. Refresh your access token when it expires.

📘

For more information about OAuth 2.0

• A basic introduction to OAuth 2.0, with Grant Type: Client Credentials as the most relevant section
• OAuth 2.0 Servers
• The OAuth section of our Terms and Definitions

Alternatively, you can probably use a library in your preferred language to do much of this.

Prerequisites

• You must already have created an OAuth 2.0 access key or API key. You can find instructions for doing so in Create API Credentials.
• You must have your OAuth Client ID and OAuth Client Secret you saved to run the examples as you go through this guide.

Replace example data with your data

The following examples all use fake test information for a fake organization. You should replace the values shown in this table with your organization's specific account values. Shipium uses the term partner to refer to our customers. Partner used in the following table refers to your organization.

Authenticate and get a token for use in other APIs

This section describes how to get a token that your organization can use to start making calls to Shipium's APIs.

👉

What we mean by resources

Shipium's APIs, as well as other APIs, are referred to as resources in the OAuth 2.0 terminology.

Retrieve an access token

This is step 1. You will use the access token this generates in the following steps.

Replace the oauthClientId and oauthClientSecret in the following client uniform resource locator (cURL) request example with your own values. Keep the AUTHORIZATION_SERVER line as is.

PARTNER_OA_CLIENT_ID='oauthClientId';
PARTNER_OA_SECRET='oauthClientSecret';
AUTHORIZATION_SERVER='https://auth.shipium.com';

curl --request POST --location "$AUTHORIZATION_SERVER/oauth/token" \
  --user "$PARTNER_OA_CLIENT_ID:$PARTNER_OA_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials'

You should receive a JavaScript Object Notation (JSON) response like the following (this example is pretty-printed for clarity):

{
  "access_token":"Q8ZUeEJHcv2uhfsco=",
  "token_type":"bearer",
  "expires_in":6008,
  "scope":"auth-service shiptime-service",
  "partnerId":"3060a3db-0678-4459-bd2e-f7c501ee4b3f",
  "partnerIds":"3060a3db-0678-4459-bd2e-f7c501ee4b3f",
  "userId":"BOZSGCL4SMOEDSKA96ZK"
}

You will need the access token value returned by the recipe in the following steps.

👉

For Postman users

You can find more information about OAuth 2.0 and how to use the Authorization tab in this documentation.

Validate your access by calling the ping API

This is (optional) step 2. You can check to ensure a proper connection.

👍

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

To validate:

1. Replace <ACCESS_TOKEN> in the first line below with the access token you received in the response to step 1, including its trailing =. Keep the RESOURCE_SERVER as shown in this example.
2. Make the cURL request shown below.

ACCESS_TOKEN='<ACCESS_TOKEN>';
RESOURCE_SERVER='<<api_url>>';

curl -X GET \
  --url "$RESOURCE_SERVER/api/v1/deliveryexperience/ping" \
  --header 'accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN" ;

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

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

🚧

Common error

If you receive a message like the following, this may be due to a failure to paste the ACCESS_TOKEN value:
{"error":"invalid_token","error_description":"Invalid access token: xxxxxxxxxxxxxxxxxxxxx"}

Make sure the whole value was copied, including the trailing =.

Refresh an expired access token

This is step 4. You will use the initial token for some time before you need to follow the steps here to refresh your access token.

When you retrieved your initial access token, the response contained an element called expires_in, which is the number of seconds before the token must be refreshed. Once this time period has elapsed, your calls will fail due to your access token being invalid and you'll receive a 401 response from the server.

You must refresh your token by calling the /oauth/token endpoint again as in the original example.

PARTNER_OA_CLIENT_ID='shipium_provided_user';
PARTNER_OA_SECRET='SomeFairlyLongRandomLookingString';
AUTHORIZATION_SERVER='https://auth.shipium.com';

AUTH=`echo -ne "$PARTNER_OA_CLIENT_ID:$PARTNER_OA_SECRET" | base64`;
  
curl --location --request POST "$AUTHORIZATION_SERVER/oauth/token" \
  --user "$PARTNER_OA_CLIENT_ID:$PARTNER_OA_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials';

Once you've refreshed your authorization, you can call ping again to confirm your connection.

📘

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