Authorization

To create secure access to Shippo Shipping Elements follow this guide.

Background

There are two ways for you to enable your user to create their own shipping labels using Shipping Elements. Shipping Elements supports both gray label and white label integrations.

• Using a white label integration means that you create and manage you users accounts using Shippo Platforms . Shippo bills your account and you're responsible for billing users. This provides a seamless experience for your user. You have access to all account details including access keys.
• Using a gray label integration means that you guide your user to create their own Shippo account that you have access to using OAuth . Shippo will bill your users directly.

For each use case, keys are long lived and suitable only for server-side communication where the key can be kept private. For secure access to Shippo accounts using Shippo Shipping Elements, this guide details how to obtain a short lived token (JSON Web Token (JWT)). These JWT expire after 12 hours.

Follow the steps here to generate a JWT.

White label integration

If you have not already, review our guide on Shippo Platform accounts. You must have a Platforms account to create and use Managed Shippo Accounts.

1. Retrieve your user's Shippo Account ID

When you create a Shippo Managed account for your user, the response includes an object_id that you will use to reference that account. This is the Shippo Account ID that you can use to make API calls representing that account. When you create the account, you should save this object_ id along with your users account credentials.

If you need to retrieve a Shippo Account ID of an account, you can request a list of all your Managed Shippo Accounts.

  curl --location --request GET 'https://api.goshippo.com/shippo-accounts/' \
  --header 'Authorization: ShippoToken <API_TOKEN>' \
  --header 'Content-Type: application/json'

The response includes the object_id for each account.

2. Generate your own JWT using direct authorization API

To generate a JWT for a Managed account, call the embedded/authz/ endpoint and set the object_id from the previous step to the SHIPPO-ACCOUNT-ID in the header of the call.

curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'SHIPPO-ACCOUNT-ID: e0b382dc7d754c0ca6358c09d5d2bdf7' \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'

The following is the expected response.

// response
{
  "token":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", 
  "expires_in": "1682364890"
}

Where token is the JWT and expires_in is a unix timestamp representing when the token expires.

Get your OAuth key

If you have not already, follow the steps in our guide to request your OAuth key and get access to a Bearer Token.

Generate your own JWT

There are 2 ways you can generate your own JWT.

Direct Authorization API

The first way to generate your JWT is to call the /embedded/authz/ endpoint. Send the following request. Remember to replace <OAUTH_BEARER_TOKEN> with your Bearer Token.

curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: Bearer <OAUTH_BEARER_TOKEN> \
--header 'Content-Type: application/json' \
--data-raw '{
    "scope": "embedded:carriers"
}'

The following is the expected response.

// response
{
  "token":      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", 
  "expires_in": "1682364890"
}

Where token is the JWT and expires_in is a unix timestamp representing when the token expires.

User Server Side Remote Procedure Call to generate JWT

The second way to generate your JWT is to use RPC.

service user {
  rpc DirectAuthorization(DirectAuthorizationRequest) : DirectAuthorizationResponse
}

message DirectAuthorizationRequest {
 context
 requestor: // integration user id
 requested_subject: // alice's id
 token_type: 'jwt'
}

Expected Response

message DirectAuthorizationResponse {
  token: 
  // encoded jwt
  expires: 
  //unix timestamp representing when the token expires
}

Validate your JWT

JWT works the same as an API token. To test your generated JWT, call the list all carrier parcel templates endpoint. Remember to replace <JWT_TOKEN> with the token you have generated.

curl --location --request GET https://api.goshippo.com/parcel-templates  \
    --header 'Authorization: JWT <JWT_TOKEN>' \
    --header 'Content-Type: application/json'

If your JWT is functioning correctly, you should see a response like this.

[
  {
    "name": "FedEx® Small Box (S1)",
    "token": "FedEx_Box_Small_1",
    "carrier": "FedEx",
    "is_variable_dimensions": false,
    "length": "12.375",
    "width": "10.875",
    "height": "1.5",
    "distance_unit": "in"
  }
]

Strategy for generating JWT

Your generated JWT expires after 12 hours. When integrating Shippo Shipping Elements, consider how you will automatically generate this for your user. The flow below shows how to generate a JWT and how to refresh an expired JWT for your user. Use this with the Shipping Elements events to integrate the token generation into your site.