> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

Authentication (is the caller who they say they are?) and authorization (are they allowed to do this?) are handled by passing a [JWT](https://jwt.io/) (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.

<Note>
  See [Find Your URL](/home/find-your-url) for information on finding the correct URL to use for your ShipStream instance.
</Note>

The JWT token is typically obtained by creating a [Custom Global Integration](https://help.shipstream.io/article/15i0ut0c8e-global-integrations#custom_integrations) 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:

```http theme={null}
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>
  #### 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.
</Danger>

## Inspecting Tokens

To inspect the contents of a JWT token, you can use online tools such as [jwt.io](https://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.