OAuth

To get started, please contact our sales team with the following information.

• Company's Name:  This is presented to the user during the OAuth flow when they connect their Shippo account to your platform
• Callback URL:  The URL vendors are redirected to after they connect their Shippo account. This is your site URL followed by /shippo-oauth-redirect/
• Contact Email:  Your email address
• Brief description of use case

Here's a template you can copy and paste to quickly draft the message for our team. You can paste this information in the Additional Details: section.

Hi,

I need OAuth credentials for my platform. I've included all requisite information below.

-   Company Name:
-   Callback URL:
-   Contact Email:
-   Use Case Description:

Please let me know if you have any questions.

Thanks,

<Your Name>

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:

curl 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 <OAUTH_BEARER_TOKEN>"\
    -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_BEARER_TOKEN>"\
    -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.

OAuth Redirects

After your user has logged into their Shippo account, they are redirected back to your site. By default, you defined this redirect by the URL (Callback URL) you sent to our support team when setting up your OAuth.

During development and testing, it may be useful for you to be able to change your callback URL. For example, you may want to redirect to a development server while you build your integration. Depending on your development strategy, you might add redirects for development, test, production, or even localhost.

To control which redirect URL you use, include the query parameter &redirect_uri followed by the URL you want to redirect your user to after they have logged into their Shippo account. If you do not specify a &redirect_uri, your default redirect URL is used.

The following example shows a redirect to the site https://mysite.com/. It’s important to note the closing / on your URI is required.

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