Skip to main content
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. Generate your PAT from the ShipBob dashboard by going to Integrations > API Tokens > Generate New Token.
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: 
{
  "items": [
    {
      "id": 56232,
      "name": "PAT Channel",
      "application_name": "SMA",
      "scopes": ["billing_read", "channels_read", "orders_read", "fulfillments_read", "fulfillments_write", "inventory_read", "inventory_write", "locations_read", "orders_read", "orders_write", "pricing_read", "products_read", "products_write", "receiving_read", "receiving_write", "returns_read", "returns_write", "webhooks_read", "webhooks_write"]
    }
  ]
}
The channel ID you should use when making POST requests is the channel ID that has _write scopes.

​
OAuth Flow

To authenticate via OAuth, follow these steps:

​
Step 1: Create App

Generate credentials from the ShipBob dashboard by going to Integrations > OAuth Apps > Create App. See more here.
If you want to test on a sandbox account here is the link to create one.

​
Step 2: Request Permission to Access User Data

Once you have your client ID and secret, you can use them to get a user’s permission to access their account data. You start by making a request to the following endpoint: 
GET https://auth.shipbob.com/connect/authorize
Use https://authstage.shipbob.com/connect/authorize if on sandbox.
The following query parameters are allowed for this endpoint:
ParameterValuesRequired?
client_idClient id provided by step 1.required
scopeOne or more scopes granted by step 1, space-separated. NOTE: if you want to take advantage of refresh tokens (aka offline access mode) you must additionally request the offline_access scope.required
redirect_uriThe callback URI ShipBob will call after the user responds to the request for consent. Must match one of the provided values from step 1.required
response_modeIf you include this query parameter with value form_post then we will make a POST request to your callback URL, instead of including the data as a fragment.optional
integration_nameName of the integration for this particular user. We recommend that you know the user’s store name on your platform. If not provided, the user will be prompted to provide their name or choose one from a drop-down of options.recommended
stateApplication-provided string to help prevent replay attacks. Echoed back to the application in the callback for validation.recommended
nonceA random string you can send and we will send it back within the token, to prevent replay attacks, code substitutions, etc.recommended
These parameters must be URL encoded, particularly redirect_uri.
A very basic example call to our integrate endpoint will look like this: 
GET https://auth.shipbob.com/connect/authorize?
   client_id=ExternalApplication_123
   &scope=billing_read channels_read fulfillments_read fulfillments_write inventory_read inventory_write locations_read orders_read orders_write pricing_read products_read products_write receiving_read receiving_write returns_read returns_write webhooks_read webhooks_write offline_access
   &redirect_uri=https%3A%2F%2Fwww.myapp.com%2Fintegrate%2Fshipbob%2Fcallback
   &response_mode=form_post
   &integration_name=MyCoolApp
Interactive Authorization URL Builder Fill in your details and the URL will be generated live:

​
Step 3: Implement Your Callback URI

When the user grants access, ShipBob redirects to your callback URI with the following parameters: 
POST https://www.myapp.com/integrate/shipbob/callback
Response 
{
  "id_token": "some_open_id_token",
  "code": "some_access_code",
  "scope": "billing_read channels_read fulfillments_read fulfillments_write inventory_read inventory_write locations_read orders_read orders_write pricing_read products_read products_write receiving_read receiving_write returns_read returns_write webhooks_read webhooks_write offline_access openid",
  "session_state": "some_session_state",
}

​
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=ExternalApplication_123
  &client_secret=someSecret
  &code=code_from_step_3
  &grant_type=authorization_code
Response 
{
  "id_token": "some_open_id_token",
  "access_token": "your_api_token",
  "expires_in": 3600,
  "token_type": "bearer",
  "refresh_token": "ABCDEFGHIJKLMNOPQRSTUVWABCDEFGHIJKLMNOPQRSTUVWXYZ123456789012345-1",
  "scope": "billing_read channels_read fulfillments_read fulfillments_write inventory_read inventory_write locations_read orders_read orders_write pricing_read products_read products_write receiving_read receiving_write returns_read returns_write webhooks_read webhooks_write offline_access openid"
}
Use https://authstage.shipbob.com/connect/token if using sandbox.

​
Step 5: Refresh Token

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=ExternalApplication_123
  &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. A new refresh_token will be generated every time you create a new access_token.

​
Step 6: Retrieve Your Channel ID

Most of the POST requests on the ShipBob API require you to include a shipbob_channel_id in the header. Retrieve it via: 
GET https://api.shipbob.com/2025-07/channel
Example Response: 
{
  "items": [
    {
      "id": 56232,
      "name": "MyCoolApp",
      "application_name": "MyCoolApp",
      "scopes": ["billing_read", "channels_read", "orders_read", "fulfillments_read", "fulfillments_write", "inventory_read", "inventory_write", "locations_read", "orders_read", "orders_write", "pricing_read", "products_read", "products_write", "receiving_read", "receiving_write", "returns_read", "returns_write", "webhooks_read", "webhooks_write"]
    }
  ]
}
The channel ID you should use is the channel ID that has _write scopes.
If you are using a ShipBob sandbox account, make sure to update your endpoint to https://sandbox-api.shipbob.com/2025-07/channel. You’re now ready to make authenticated API requests using ShipBob!