> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.goshippo.com/feedback
```json
{
"path": "/docs/ShippingElements/auth",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Authorization
> Set up secure authorization for Shippo Shipping Elements using JWT tokens for white label and gray label integrations.
To create secure access to Shippo Shipping Elements follow this guide.
## Background
There are two ways for you to enable your user to create their own shipping labels using Shipping Elements.
Shipping Elements supports both gray label and white label integrations.
* Using a white label integration means that you create and manage you users accounts using [Shippo Platforms](/docs/PlatformAccounts/platform_accounts). Shippo bills your account and you're responsible for billing users. This provides a seamless experience for your user. You have access to all account details including access keys.
* Using a gray label integration means that you guide your user to create their own Shippo account that you have access to using [OAuth](/docs/OAuth_Integrations/OAuth). Shippo will bill your users directly.
For each use case, keys are long lived and suitable only for server-side communication where the key can be kept private.
For secure access to Shippo accounts using Shippo Shipping Elements, this guide details how to obtain a short lived token ([JSON Web Token (JWT)](https://jwt.io/)). These JWT expire after 12 hours.
Follow the steps here to generate a JWT.
## White label integration
If you have not already, review our guide on [Shippo Platform accounts](/docs/PlatformAccounts/platform_accounts). You must have a Platforms account to create and use Managed Shippo Accounts.
### 1. Retrieve your user's Shippo Account ID
When you [create a Shippo Managed account](/docs/PlatformAccounts/platform_using_accounts#create-a-managed-shippo-account-for-your-customer) for your user, the response includes an `object_id` that you will use to reference that account. This is the Shippo Account ID that you can use to make API calls representing that account. When you create the account, you should save this `object_ id` along with your users account credentials.
If you need to retrieve a Shippo Account ID of an account, you can request a list of all your Managed Shippo Accounts.
```shell cURL theme={null}
curl --location --request GET 'https://api.goshippo.com/shippo-accounts/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json'
```
The response includes the `object_id` for each account.
### 2. Generate your own JWT using direct authorization API
To generate a JWT for a Managed account, call the `embedded/authz/` endpoint and set the `object_id` from the previous step to the `SHIPPO-ACCOUNT-ID` in the header of the call.
```shell cURL theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: ShippoToken ' \
--header 'SHIPPO-ACCOUNT-ID: e0b382dc7d754c0ca6358c09d5d2bdf7' \
--header 'Content-Type: application/json' \
--data-raw '{
"scope": "embedded:carriers"
}'
```
The following is the expected response.
```json theme={null}
// response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"expires_in": "1682364890"
}
```
Where `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.
## Get your OAuth key
If you have not already, follow the steps in our [guide to request your OAuth key and get access to a Bearer Token](/docs/OAuth_Integrations/OAuth).
## Generate your own JWT
There are 2 ways you can generate your own JWT.
#### Direct Authorization API
The first way to generate your JWT is to call the `/embedded/authz/` endpoint.
Send the following request. Remember to replace `` with your Bearer Token.
```shell theme={null}
curl --location --request POST 'https://api.goshippo.com/embedded/authz/' \
--header 'Authorization: Bearer \
--header 'Content-Type: application/json' \
--data-raw '{
"scope": "embedded:carriers"
}'
```
The following is the expected response.
```json theme={null}
// response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"expires_in": "1682364890"
}
```
Where `token` is the JWT and `expires_in` is a unix timestamp representing when the token expires.
#### User Server Side Remote Procedure Call to generate JWT
The second way to generate your JWT is to use RPC.
```JAVA theme={null}
service user {
rpc DirectAuthorization(DirectAuthorizationRequest) : DirectAuthorizationResponse
}
message DirectAuthorizationRequest {
context
requestor: // integration user id
requested_subject: // alice's id
token_type: 'jwt'
}
```
Expected Response
```JAVA theme={null}
message DirectAuthorizationResponse {
token:
// encoded jwt
expires:
//unix timestamp representing when the token expires
}
```
## Validate your JWT
JWT works the same as an API token. To test your generated JWT, call the [list all carrier parcel templates](/api-reference/carrier-parcel-templates/list-all-carrier-parcel-templates) endpoint. Remember to replace `` with the token you have generated.
```shell theme={null}
curl --location --request GET https://api.goshippo.com/parcel-templates \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json'
```
If your JWT is functioning correctly, you should see a response like this.
```json theme={null}
[
{
"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"
}
]
```
## Strategy for generating JWT
Your generated JWT expires after 12 hours. When integrating Shippo Shipping Elements, consider how you will automatically generate this for your user.
The flow below shows how to generate a JWT and how to refresh an expired JWT for your user. Use this with the [Shipping Elements events](/docs/ShippingElements/events) to integrate the token generation into your site.
