Authentication

Shippo authenticates your API requests using your account’s API keys.

note

If your request does not include a key, or includes a deleted or expired key, the Shippo API returns a 401 Unauthorized error with the following responses, depending on the nature of the error.

Copy
Copied
{
    "detail": "Token does not exist"
}

Or

Copy
Copied
{
    "detail": "Authentication credentials were not provided."
}

Test mode and live mode

You can make Shippo API calls in either test mode or live mode. When you use test mode, you have access to test data and can make test calls. When you use live mode, you have access to live data and can make live calls (like purchasing a label). Each mode has its own set of API keys.

Type When to use How to use Considerations
Test mode As you test and build your Shippo integration, use test mode with your test keys. In test mode, you can use all of the Shippo services like retrieving shipping rates and creating test labels without being charged. Use your API test token for Authentication in your API calls. Rates requested in test mode may differ from actual rates in live mode. Data is not shared between test account and live account.

For a full list of considerations, review our testing guide
Live mode When your integration is ready for production use live mode with your live tokens. In live mode, you can generate shipping rates and purchase real shipping labels. Use you API live token for Authentication in your API calls Your account will be charged for purchasing labels.

Get your API keys

Create your free Shippo account

If you already have a Shippo account, skip ahead to Step 2.

In your browser, open the address https://apps.goshippo.com/join. Enter your name, email, a secure password, and click Get Started.

Follow the prompts to complete your registration.

Generate your secure key

Login to the Shippo API portal using your Shippo credentials.

generate token UI

In the API Configuration menu, select Developer keys. In Developer Keys, there are two options. Live keys and Test keys. Use Live keys for production ready use of the Shippo API. For testing and development, use the Test key.

  • Click Create new live key for a live key.
    • Live keys begin with shippo_live_ .
  • Click Create new test key for a test key.
    • Test keys begin with shippo_test_ .

Copy your API key and click Close.

Note

You can only see your full API key once. Store it in a secure place. If you lose your API key, you can generate a new one.

Warning

These keys give direct access to your Shippo account. You must store these securely. If you think your key has been compromised, use the dashboard to delete it and generate a new key.

Use your secure key

To use your secure key, make an API call replacing <API_TOKEN> with the key you have generated.

Copy
Copied
curl https://api.goshippo.com/shipments/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -H "Content-Type: application/json"\
    -d '{...}'