Skip to main content
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.
noteDepending on the path you choose for integration, there is a different set of instructions. Refer to our integration paths for more details.

​
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.
JWT for eCommerce merchant request
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"
}'
JWT for eCommerce merchant response
{
  "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.
JWT for white label request
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"
}'
JWT for white label response
{
  "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

JWT for gray label request
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"
}'
JWT for gray label response
{
  "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'
}
Response
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.
Use JWT request
curl --location --request GET https://api.goshippo.com/parcel-templates  \
    --header 'Authorization: JWT <JWT_TOKEN>' \
    --header 'Content-Type: application/json'
Use JWT response
[
  {
    "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"
  }
]