About OAuth 2.0-based authentication

Shipium supports the use of OAuth 2.0 clients to authorize requests to connect with our application programming interfaces (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. The steps are as follows:

Alternatively, you can probably use a library in your preferred language to do much of this, or mechanically follow the steps in this document.

📘

For more information

See these resources 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 Common Terms and Definitions

Prerequisites

• You must already have created an OAuth 2.0 access key or API key. See Creating 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.

Replacing 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 your organization, as it appears in the "Sample value in examples" table column.

Authenticating and getting a token for use in other APIs

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

Retrieving 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 example with your own values. Keep the AUTHORIZATION_SERVER line as is. Make the client uniform resource locator (cURL) request as shown:

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 documentation about OAuth 2.0 and how to use the Authorization tab here.

Validating your access by calling the ping API

This is (optional) step 2. It lets you check that things are working correctly.

👍

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 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 the 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 this:

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

Refreshing an expired access token

This is step 4. You will have been using 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. 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.

Terminology guide

See Common Terms and Definitions.