JSON Web Tokens

ShipEngine partners that have registered a client with us can use JSON Web Tokens (JWTs) to authenticate with ShipEngine instead of using API keys or the On-Behalf-Of header.

This is more secure for server-to-server communication since JWTs can be given expiration times, but can be particularly useful when you need to delegate access to a party or environment where you have limited trust (e.g. delegating access to a customer's web browser for using ShipEngine Elements).

Getting Started

To get started, get in touch with your ShipEngine technical contact and discuss the creation of a client. You'll need to agree on a name for the client and have a discussion about scopes you'll want to be able to claim (see below) as well as the partner ID you'll want to be able to claim (for most partners, there will be only one relevant partner ID).

Then you'll need to generate a public/private key pair and register the public key with ShipEngine. To create a key pair, run these commands in your terminal:

1
2
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out $(date -Idate)-public.pem

This will create two files: private.pem and 2023-07-06-public.pem (your file name will differ depending on the date you run the command). Feel free to change these file names to whatever helps you best remember what they are for, but please keep the date in the public key name. Keep the private key safe and secure. Send the public key to your technical contact at ShipEngine; they will give you a key ID in return, which will be used when creating tokens.

Creating JWTs

Most popular languages have library support for creating and signing JWTs. Please refer to their documentation for specific support questions. Using your private key, you must sign your key using the RS256 algorithm.

Header Claims

The claims to make in your JWT's header are as follows:

Claim Name	Claim Description	Type & Functionality
`typ`	type	This must be the literal string `"JWT"` because you are making a JSON Web Token.
`alg`	algorithm	This must be the string `"RS256"` which is the algorithm to use to sign the JWT.
`kid`	key id	The name of the public key registered with ShipEngine that pairs with the private key used for signing. The client claimed in the `iss` claim (below) needs to be configured to be able to use this key. Get this name from your technical contact (see above).

Payload Claims

The claims to make in your JWT's payload are as follows:

Claim Name	Claim Description	Type & Functionality
`iat`	issued at	The integer epoch time that the token was generated.
`exp`	expiration	The integer epoch time after which the token should no longer be honored. Shorter is more secure. 30 seconds is ideal. It should be no longer than 5 minutes, especially for low-trust environments like a user's web browser. (e.g. ShipEngine Elements) It is important for this to be as short as you can stand.
`tenant`	account id	The ID (as a string) of the account that is the subject of the request. Optional for endpoints that do not operate on accounts.
`partner`	partner id	The ID (as a string) of the partner that you wish to make the request as. Required in almost all cases.
`iss`	issuer	The name of the client registered with ShipEngine that is making the request. In combination with the `partner` claim, this is used to check for validating access to an account's data where appropriate. The client needs to be configured to be able to use the key claimed in the `kid` claim (above).
`scope`	scopes	A space-separated list of the access scopes associated with this token. If this is left out, ShipEngine will act as if you claimed all the scopes you are allowed to claim. When creating a JWT to be used in requests from an environment you control (such as your own server) this can be as broad as you like or left as the default. When creating a JWT to be used in requests from an environment you do _not_control (such as with ShipEngine Elements) it is most secure to limit the scopes claimed to only the ones needed for the task at hand.