OAuth

Please reach out to partnerships@goshippo.com to register as a platform and get your client_id.

As a platform, implementing standalone accounts via OAuth is the best option to integrate Shippo if you want to offer shipping features within your platform, but don’t want to handle all the billing or communication administration.

You can build all the required shipping features into your platform as normal. Then, your users can sign up for their own Shippo account via our OAuth flow and use their own API tokens to authenticate all shipping requests.

The OAuth Connection Flow

The following process applies for setting up a Shippo account for a user on your platform:

  • Step 1: Starting on your site, the users clicks a link or button that takes them to the Shippo OAuth flow. The user is prompted to login or register for a Shippo account and, if missing, enter billing information (e.g. credit card). Finally, the user grants your platform permission to access their Shippo account.
  • Step 2: The user is then redirected back to your site, passing along either an authorization code or an error in case the user chose not to complete the OAuth flow.
  • Step 3: You need to make a request to our OAuth token endpoint to fetch the user’s account ID and store it on your platform.

After all steps have been completed, your platform can make API requests on behalf of your users using their authentication credentials.

Step 1: Link to the Shippo OAuth flow

To initiate the OAuth flow, your platform needs to link to the following URL:

https://goshippo.com/oauth/authorize?response_type=code&client_id=YOUR_PARTNER_ID&scope=*&state=YOUR_RANDOM_STRING

The endpoint accepts the following query parameters:

  • response_type: “code”
  • client_id: your unique partner ID
  • scope: “*” (currently this is the only supported scope, allowing you full Shippo API access)
  • state, a random string generated by your application, which you’ll verify later to prevent CSRF attacks

After the user clicks on the link in your application, they’ll be taken to Shippo’s website to complete the OAuth process.

Unlike most OAuth implementations (like “Facebook Connect” or “Sign In with Twitter”), we’ve seamlessly added the process of creating a Shippo account right into our authorization flow. You don’t have to worry about whether or not your users already have accounts!

The user has to complete the following steps on the Shippo OAuth flow:

  1. Register a new Shippo account or login with an existing account.
  2. If missing, enter billing information (e.g. credit card) to enable their Shippo account for production label purchase and other paid Shippo features.
  3. Grant your platform permission to access their account.

The process looks as follows:

Step 2: Redirect to Your Site

After the user completed the OAuth flow, they are redirected back to your site’s redirect_uri:

https://www.example-app.com/shippo-oauth-redirect?code=AUTH_CODE_HERE&state=my_random_string_def456

The request includes the following query parameters:

  • code: the authorization code
  • state: the random string you passed in step 1

You should first compare the state value to ensure it matches the one you started with in step 1. You can typically store the state value in a cookie or session, and compare it when the user comes back. This ensures your redirection endpoint isn’t able to be tricked into attempting to exchange arbitrary authorization codes.

If the authorization was denied by the user, they’ll still be redirected back to your site, but the URL includes an error instead of the authorization code:

https://www.example-app.com/shippo-oauth-redirect?error=access_denied&error_description=The%20user%20denied%20your%20request&state=my_random_string_def456

Step 3: Fetching User Credentials via Token Exchange

In the last step you use the code from step 2 to fetch your user’s access token, which you need for API authentication:

https://goshippo.com/oauth/access_token \
    -d client_id=partner_abc123 \
    -d client_secret=ef3034c9d025c62536e78ca0ccf9974cc2a75099 \
    -d code=AUTH_CODE_HERE \
    -d grant_type=authorization_code \
    -X POST

The endpoint accepts the following parameters:

  • client_id: your unique partner ID
  • client_secret: your Shippo OAuth API secret key (different from your Shippo API key)
  • code: the authorization code provided in step 2
  • grant_type: “authorization_code”

Shippo then returns the authentication credentials for the user:

{
    "access_token": "oauth.612BUDkTaTuJP3ll5-VkebURXUIJ5Zefxwda1tpd.U_akmGaXVQl80CWPXSbueSG7NX7sNe_HvLJLN1d1pn0=",
    "scope": "*",
    "token_type": "bearer"
}

The response contains the following parameters:

  • token_type: “bearer”
  • scope: “*”
  • access_token: the access you use to make API calls on behalf of your user. It never expires.

Please note that Shippo doesn’t expire the access_token. It remains valid forever and you don’t need to implement a refresh mechanism.

If the token exchange request fails, you get back an error response:

{
    "error": "invalid_grant",
    "error_description": "Invalid user credentials"
}

Authentication

Once you have completed the OAuth flow for a user, you can make Shippo API requests on behalf of this user by authenticating via the normal Authorization header. You need to set the header like this:

curl https://api.goshippo.com/shipments/  \
    -H "Authorization: Bearer " \
    -H "Content-Type: application/json"  \
    -d "{...}"

Versioning

Since your users might independently upgrade the API version of their Shippo account, it’s important that you explicitly set your API version in all of your API calls that you make on behalf of your users. You can set the API version in the header like this:

curl https://api.goshippo.com/shipments/  \
    -H "Authorization: Bearer oauth.612BUDkTaTuJP3ll5-VkebURXUIJ5Zefxwda1tpd.U_akmGaXVQl80CWPXSbueSG7NX7sNe_HvLJLN1d1pn0=" \
    -H "Content-Type: application/json"  \
    -H "Shippo-API-Version: 2018-02-08" \
    -d "{...}"

Please note that all API requests made on behalf of another Shippo user require API version 2018-02-08 or higher.

Get Started Today for Free!

Kick the tires on the best-in-class shipping platform with a free Shippo account.