ShipBob’s Developer API allows two forms of authentication, depending on the use case: Personal Access Token (PAT) or OAuth 2.0.

​
Prerequisites

To generate authentication credentials, you must have an account on the ShipBob dashboard. If you don’t have one, you can sign up:

​
Supported Authentication Methods

ShipBob offers two authentication methods based on integration needs:

​
Personal Access Token (PAT) Flow

If you’re building a single-user custom integration, use this method. It generates a ready-to-use bearer-type token with full access to the merchant’s account.

​
OAuth Flow

If you are building a multi-user integration or an app listed on our App Store, you must use OAuth.
All API authentication operates against the root user of the account. When requesting a PAT token or installing an OAuth app, do so against the root user.

​
Personal Access Token (PAT) Flow

When you request your first PAT, ShipBob automatically generates an application (“SMA” or single-merchant application) and channel to house all your future PATs. You can request multiple tokens and revoke them anytime.
These tokens do not expire, so exercise caution when sharing them.

​
Using Your PAT

To authenticate API requests, include the PAT in the Authorization header: 
Bearer [your_api_token]
Before making API calls, retrieve your channel ID using the GET Channel endpoint: 
{
    "id": 56232,
    "name": "Personal Access Token - March 19, 2020",
    "application_name": "SMA",
    "scopes": [
        "channels_read", "orders_read", "orders_write", "products_read", "products_write",
        "receiving_read", "receiving_write", "returns_read", "returns_write", "inventory_read"
    ]
}

​
OAuth Flow

To authenticate via OAuth, follow these steps:

​
Step 1: Generate a Client ID and Secret

Generate credentials from the ShipBob dashboard:

​
Step 2: Request Permission to Access User Data

Make a GET request to: 
GET https://auth.shipbob.com/connect/authorize
Include the following query parameters (URL-encoded):
ParameterDescription
client_idYour client ID (from Step 1).
scopeSpace-separated list of scopes granted in Step 1. If using refresh tokens, include offline_access.
redirect_uriCallback URI that must match one provided during client registration.
stateRecommended for preventing replay attacks; echoed back in the callback.
nonceA random string to prevent token replay attacks.

​
Example Request

GET https://auth.shipbob.com/connect/authorize?
   client_id=MyCoolClient&
   scope=products_read channels_read offline_access&
   redirect_uri=https%3A%2F%2Fwww.myapp.com%2Fintegrate%2Fshipbob%2Fcallback

​
Step 3: Implement Your Callback URI

When the user grants access, ShipBob redirects to your callback URI with the following parameters: 
https://www.myapp.com/integrate/shipbob/callback#
   code=some_access_code&
   id_token=some_open_id_token&
   state=provided_state&
   scope=channels_read orders_read orders_write
The data returns as a fragment, not a query string.

​
Step 4: Obtain an Access Token

Exchange the authorization code for an access token by making a POST request: 
POST https://auth.shipbob.com/connect/token

redirect_uri=https%3A%2F%2Fwww.myapp.com%2Fintegrate%2Fshipbob%2Fcallback
&client_id=MyCoolApp
&client_secret=someSecret
&code=code_from_step_3
&grant_type=authorization_code

​
Response

{
  "access_token": "your_api_token",
  "expires_in": 3600,
  "token_type": "bearer"
}
If using offline_access, a refresh_token will also be provided. Use it to obtain new tokens without requiring user login: 
POST https://auth.shipbob.com/connect/token

redirect_uri=https%3A%2F%2Fwww.myapp.com%2Fintegrate%2Fshipbob%2Fcallback
&client_id=MyCoolApp
&client_secret=someSecret
&refresh_token=refresh_token_from_step_4
&grant_type=refresh_token
Access tokens expire in 1 hour. Refresh tokens are valid for 30 days.

​
Step 5: Retrieve Your Channel ID

All API requests must include shipbob_channel_id in headers. Retrieve it via: 
GET https://api.shipbob.com/1.0/channel
If you are using a ShipBob sandbox account, make sure to update your endpoint to sandbox-api.shipbob.com/1.0/channel
Example Response: 
[
  {
    "id": 12345,
    "name": "integration_name_unique_to_user"
  }
]
You’re now ready to make authenticated API requests using ShipBob!