Authentication (is the caller who they say they are?) and authorization (are they allowed to do this?) are handled by passing a JWT (JSON Web Token) in the Authorization header of the request. The token is signed with a secret key using a strong encryption algorithm, and the server verifies the signature to ensure the token is valid and to identify the caller.
See Find Your URL for information on finding the correct URL to use for your ShipStream instance.
The JWT token is typically obtained by creating a Custom Global Integration in the Admin UI. Once the token is obtained, it should be included in the Authorization header of every request to the API which requires authentication. The Authorization header should be formatted as follows: 
Authorization: Bearer {jwt_token}
Where {jwt_token} is the actual JWT token string. The server will validate the token and extract the user’s identity and permissions from it. If the token is valid, the request will be processed; if not, a “401 Unauthorized” error response will be returned indicating that authentication failed.

​
Danger, Will Robinson!

The JWT token should be kept secure and not shared with anyone. Paste it into your system’s secure storage and generate a new one if you think it has been compromised or you need additional tokens for other systems.

​
Inspecting Tokens

To inspect the contents of a JWT token, you can use online tools such as jwt.io or libraries that decode JWTs. The token consists of three parts: header, payload, and signature, separated by dots (.). The header and payload are Base64Url encoded JSON objects, while the signature is used to verify the integrity of the token. You can extract the payload to glean useful information such as:
  • aud: The ShipStream WMS instance base url for which the token is intended.
  • exp: The expiration time of the token, typically a Unix timestamp.
  • iat: The issued-at time of the token, also a Unix timestamp.

​
Expiration and Renewal

JWTs may have an expiration time to limit their validity period. When a token expires, the user must obtain a new token. The expiration time can be adjusted based on security requirements. Before making a request, you can decode the JWT token to check its expiration time (exp) to ensure it is still valid.