Authentication

ShipBob’s API supports two authentication methods: Personal Access Token (PAT) for single-user integrations and OAuth 2.0 for multi-user applications.

Prerequisites

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

Production Environment

Sandbox Environment

Our sandbox accounts are separate environments and data cannot be transferred over to production.

Choose Your Authentication Method

Personal Access Token

Best for single-user custom integrations
Quick setup, no expiration, and full account access

OAuth 2.0

Best if you want to create a multi-user app
Required for apps listed on the ShipBob App Store

All API authentication operates against the root user of the account. When requesting a PAT token or installing an OAuth app, ensure you do so with the root user credentials.

Personal Access Token (PAT) Flow

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

Generate Your Token

Navigate to the ShipBob dashboard and create your PAT:

Production
Sandbox

Go to Integrations > API Tokens > Generate New Token

When you request your first PAT, ShipBob automatically creates a Single-Merchant Application (SMA) and channel to manage your tokens. You can generate multiple tokens and revoke them anytime.

PAT tokens do not expire. Store them securely and never commit them to version control.

Add Token to API Requests

Include your PAT in the Authorization header of all API requests:

curl -X GET "https://api.shipbob.com/2025-07/channel" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Retrieve Your Channel ID

Before making POST requests, get your channel ID using the GET Channel endpoint:

curl -X GET "https://api.shipbob.com/2025-07/channel" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "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_write",
        "pricing_read",
        "products_read",
        "products_write",
        "receiving_read",
        "receiving_write",
        "returns_read",
        "returns_write",
        "webhooks_read",
        "webhooks_write"
      ]
    }
  ]
}

Use the channel ID with _write scopes when making POST requests. Include it in the shipbob_channel_id header.

OAuth Flow

OAuth is required for multi-user integrations and applications listed on the ShipBob App Store. It provides secure, granular access control with token expiration.

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:

Parameter	Values	Required?
`client_id`	Client id provided by step 1.	required
`scope`	One 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_uri`	The 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_mode`	If 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_name`	Name 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
`state`	Application-provided string to help prevent replay attacks. Echoed back to the application in the callback for validation.	recommended
`nonce`	A 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!

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)

Want to make your app available to all ShipBob merchants? Publishing to the App Store allows any ShipBob user to discover and install your integration.

Submit App for Review

In the ShipBob dashboard, navigate to Integrations > OAuth Apps, find your app, and click Publish in the Action column.Required Information:

App Icon (500x500px, .png or .jpeg)
This image represents your app in the ShipBob App Store. Choose a clear, recognizable logo.
Integration Description (max 500 characters)
Highlight key features, benefits, and use cases. Focus on what problems your app solves for merchants.
Support Documentation Link
Provide a URL to help articles or guides that explain how to use your integration.
Support Email
Enter a support email address where users can reach your team for questions or issues.
Install URL
This is where users will be redirected when they click Get App in the ShipBob App Store. It should route to your OAuth authorization flow (Step 2).

Click Submit for Review.Your app’s status will update to In Review.

Review Process

The ShipBob team will review your app within 1-3 business days.They may contact the user listed under the Created By column if additional details or changes are needed.

Prepare for potential questions about your app’s functionality, security practices, and user experience.

Approval & Listing

Once approved, your app will be listed in the ShipBob App Store.ShipBob merchants can now discover and install your app.

Monitor your support email for user questions and feedback after launch. A responsive support experience helps build trust with merchants.

App Store Listing Best Practices

Clear Icon: Use a simple, recognizable logo that looks good at small sizes
Compelling Description: Focus on merchant benefits, not just technical features
Quality Documentation: Provide step-by-step setup guides and troubleshooting tips
Responsive Support: Answer merchant questions promptly to build trust
Test Thoroughly: Ensure your OAuth flow works flawlessly before submitting

Quick Reference

Environment URLs

Production

Auth URL: https://auth.shipbob.com
API Base: https://api.shipbob.com
Dashboard: https://web.shipbob.com

Sandbox

Auth URL: https://authstage.shipbob.com
API Base: https://sandbox-api.shipbob.com
Dashboard: https://webstage.shipbob.dev

Common Headers

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

Token Lifetimes

Token Type	Lifetime	Notes
PAT	Never expires	Revoke manually from dashboard
OAuth Access Token	1 hour	Refresh before expiration
OAuth Refresh Token	30 days	New one issued with each refresh

Security Best Practices

✅ Store tokens securely (e.g., encrypted database, secrets manager)
✅ Never commit tokens to version control
✅ Use HTTPS for all API requests
✅ Implement proper error handling for expired tokens
✅ Validate state parameter in OAuth callbacks
✅ Use offline_access scope only when necessary
✅ Regularly rotate PAT tokens
⛔ Don’t expose tokens in client-side code
⛔ Don’t share tokens between environments

Get Started

Use Cases

Other

Prerequisites

Production Environment

Sandbox Environment

Choose Your Authentication Method

Personal Access Token

OAuth 2.0

Personal Access Token (PAT) Flow

OAuth Flow

Step 1: Create App

Step 2: Request Permission to Access User Data

Step 3: Implement Your Callback URI

Step 4: Obtain an Access Token

Step 5: Refresh Token

Step 6: Retrieve Your Channel ID

Step 7: Test Your App (Optional)

Step 8: Publish in ShipBob App Store (Optional)

Quick Reference

Production

Sandbox

Get Started

Use Cases

Other

​Prerequisites

Production Environment

Sandbox Environment

​Choose Your Authentication Method

Personal Access Token

OAuth 2.0

​Personal Access Token (PAT) Flow

​OAuth Flow

​Step 1: Create App

​Step 2: Request Permission to Access User Data

​Step 3: Implement Your Callback URI

​Step 4: Obtain an Access Token

​Step 5: Refresh Token

​Step 6: Retrieve Your Channel ID

​Step 7: Test Your App (Optional)

​Step 8: Publish in ShipBob App Store (Optional)

​Quick Reference

​Production

​Sandbox

Prerequisites

Choose Your Authentication Method

Personal Access Token (PAT) Flow

OAuth Flow

Step 1: Create App

Step 2: Request Permission to Access User Data

Step 3: Implement Your Callback URI

Step 4: Obtain an Access Token

Step 5: Refresh Token

Step 6: Retrieve Your Channel ID

Step 7: Test Your App (Optional)

Step 8: Publish in ShipBob App Store (Optional)

Quick Reference

Production

Sandbox