Authentication

Prerequisites

Before you begin, you’ll need a ShipBob account. Choose your environment:

Choose Your Authentication Method

Personal Access Token (PAT) Flow

This is best for single-user custom integrations and quick setup, no expiration and full account access.

$
curl -X GET "https://api.shipbob.com/2026-01/channel" \
>
  -H "Authorization: Bearer YOUR_API_TOKEN"

$
curl -X GET "https://api.shipbob.com/2026-01/channel" \
>
  -H "Authorization: Bearer YOUR_API_TOKEN"

1
{
2
  "items": [
3
    {
4
      "id": 56232,
5
      "name": "PAT Channel",
6
      "application_name": "SMA",
7
      "scopes": [
8
        "billing_read",
9
        "channels_read",
10
        "orders_read",
11
        "fulfillments_read",
12
        "fulfillments_write",
13
        "inventory_read",
14
        "inventory_write",
15
        "locations_read",
16
        "orders_write",
17
        "pricing_read",
18
        "products_read",
19
        "products_write",
20
        "receiving_read",
21
        "receiving_write",
22
        "returns_read",
23
        "returns_write",
24
        "webhooks_read",
25
        "webhooks_write"
26
      ]
27
    }
28
  ]
29
}

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.

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

The following query parameters are allowed for this endpoint:

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

1
{
2
  "id_token": "some_open_id_token",
3
  "code": "some_access_code",
4
  "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",
5
  "session_state": "some_session_state",
6
}

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

1
{
2
  "id_token": "some_open_id_token",
3
  "access_token": "your_api_token",
4
  "expires_in": 3600,
5
  "token_type": "bearer",
6
  "refresh_token": "ABCDEFGHIJKLMNOPQRSTUVWABCDEFGHIJKLMNOPQRSTUVWXYZ123456789012345-1",
7
  "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"
8
}

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/2026-01/channel

Example Response:

1
{
2
  "items": [
3
    {
4
      "id": 56232,
5
      "name": "MyCoolApp",
6
      "application_name": "MyCoolApp",
7
      "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"]
8
    }
9
  ]
10
}

If you are using a ShipBob sandbox account, make sure to update your endpoint to https://sandbox-api.shipbob.com/2026-01/channel.

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

Step 7: Test Your App (Optional)

• Verify the OAuth flow works end-to-end.
• Ensure scopes and permissions are correctly applied.
• Test with sandbox data before going live.

Step 8: Publish in ShipBob App Store (Optional)

Quick Reference

1
Authorization: Bearer YOUR_ACCESS_TOKEN
2
Content-Type: application/json
3
shipbob_channel_id: YOUR_CHANNEL_ID