Authentication using JWT

For server-side applications where you can keep API keys secure, follow our Authentication guide. For your client-side applications, we recommend using a JWT to securely authenticate. Following this guide to generate a JWT for your application.

Generate a JWT for an eCommerce store

If you have an eCommerce store that you want to add shipping to, you can generate a JWT using your own Shippo API key. Follow this example that uses the embedded/authz/ endpoint to create a JWT.

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

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

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

Generate a JWT for a 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.

If you do not know your customer's Shippo Account ID, refer to this guide to retrieve your user's Shippo Account ID.

To generate a JWT for a Managed account, call the embedded/authz/ endpoint and set the object_id of your customers Shippo Account ID 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"
}'

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

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

Generate a JWT for a gray label integration

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

There are 2 ways you can generate your own JWT for gray label integration.

1. Direct Authorization API

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"
}'

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

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

2. User Server Side Remote Procedure Call to generate JWT

service user {
  rpc DirectAuthorization(DirectAuthorizationRequest) : DirectAuthorizationResponse
}

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

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

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

Use 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'

[
  {
    "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"
  }
]