OAuth 2.0-based Authentication

Overview

To request authentication to use the Shipium APIs using OAuth 2.0, you use the Authorization request header.

The steps are as follows:

  1. Retrieve an Access Token using /oauth/token.
  2. (Optional) Validate your access using ping.
  3. Use the Access Token to make (authenticated) calls to the Shipium ShipTime API. This is not covered here, but in the documentation that follows.
  4. When your access token expires, repeat steps 1-3 above.

Steps 1, 2, and 4 are described in detail below.

Learn more about OAuth 2.0

If you are not familiar with the broad outlines of how OAuth 2.0 works, this article is a good introduction. The most relevant section is Grant Type: Client Credentials.

For more details, check out OAuth 2.0 Servers. For basic terms, see the OAuth section of our Common Terms & Definitions.

Alternatively, you can probably just use a library in your preferred language to do much of this or just mechanically follow the procedures described below.

Prerequisites

  • You must already have created an OAuth 2.0 access key or API key, as described in Creating API Credentials.
  • You need the OAuth Client ID and OAuth Client Secret you saved there to run the examples below.

Replacing example data with your data

The examples below all use fake test information for a fake Partner. Replace the values shown in this table with your organization's account values.

Data Element

Sample Value in Examples

Description

OAuth Client Username

$PARTNER_OA_CLIENT_ID

The OAuth Client ID provided for either test or production as appropriate.

OAuth Client Secret

$PARTNER_OA_SECRET

The OAuth Secret provided for either test or production as appropriate.

Authenticating and getting a token for use in other APIs

This describes how to get a token that you can use to work with the Shipium APIs.

📘

Note: What we mean by resources

The Shipium and other APIs are referred to as "resources" in the OAuth 2.0 terminology.

Retrieving an access token

This is the first step. You will use the access_token this generates in the following steps.

Replace the oauthClientId and oauthClientSecret in the example below with your own values and keep the AUTHORIZATION_SERVER line as shown. Make the 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 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.

📘

Note for Postman users

Postman users: You can find documentation about OAuth 2.0 and how to use the Authorization tab here.

Validating your access by calling Ping

This is the optional step 2 which lets you check that things are working correctly.

The ping API lets you debug your programmatic connection to Shipium servers during testing and integration. It always returns a JSON object with a status=1 and info="pong".

Replace <ACCESS_TOKEN> in the first line below with the access_token you received in the response to step 1 above, including its trailing =. Keep the RESOURCE_SERVER line as shown and make the cURL request shown:

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 looks like 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 token

This is step 4 in the process. You will have been using the initial token for some time before you need to do this.

When you retrieved your initial access token, the response contained an element called expires_in, the number of seconds before the token must be refreshed. Once this time period has elapsed, your calls will fail due to the access token being invalid, giving 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 have 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.


Did this page help you?