Authentication

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:

• Sign up for Production Environment
• Sign up for Sandbox Environment

​

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.

• Generate credentials from the ShipBob dashboard:
  • Production Environment
  • Sandbox Environment

​

OAuth Flow

If you are building a multi-user integration or an app listed on our App Store, you must use OAuth.

• Generate credentials from the ShipBob dashboard:
  • Production Environment
  • Sandbox Environment

​

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.

​

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:

• Production Environment
• Sandbox Environment

​

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):

​

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

​

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

​

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

Example Response:

[
  {
    "id": 12345,
    "name": "integration_name_unique_to_user"
  }
]

You’re now ready to make authenticated API requests using ShipBob!