Bearer Token authentication is designed for multi-tenant platforms and service providers who need to manage multiple merchant accounts. This method uses OAuth 2.0 access tokens obtained through the authorization flow.

Note: Bearer tokens are exclusively for multi-tenant OAuth clients. For single merchant integrations, use API Keys instead.

How It Works

Bearer Token authentication uses OAuth 2.0 access tokens to authenticate API requests on behalf of authorized merchants. Access tokens are obtained through the OAuth authorization flow and have a limited lifespan (1 hour), with refresh tokens used to obtain new access tokens.

Access Token Basics

Access Tokens: Short-lived tokens (1 hour) used for API authentication
Refresh Tokens: Long-lived tokens used to obtain new access tokens
Scope: Tokens are tied to specific merchant instances and granted permissions

For detailed information on obtaining tokens through the OAuth flow, see the OAuth 2.0 Introduction.

Authentication Method

Bearer Authentication

Use your OAuth access token with HTTP Bearer Authentication:

Authorization: Bearer <access_token>

Where <access_token> is the token received from the OAuth token endpoint.

URL Structure

With Bearer tokens, you should not include the instance ID (ie /instances/{instance_id}) in the URL, as the token automatically identifies the merchant instance.

Use:
https://app.shuttleglobal.com/c/api/[endpoint]
Not:
https://app.shuttleglobal.com/c/api/instances/{instance_id}/[endpoint]

Implementation Guide

Step 1: Obtain Access Token

First, follow the complete OAuth flow to obtain an access token. See the OAuth 2.0 Introduction for detailed instructions on:

Redirecting merchants to authorization
Exchanging authorization codes for tokens
Refreshing expired tokens

Step 2: Make API Requests

Include the access token in your Authorization header:

Example Request:

GET https://app.shuttleglobal.com/c/api/payment_links
Authorization: Bearer at_1234_h480djs93hd8
Content-Type: application/json

curl -H "Authorization: Bearer at_1234_h480djs93hd8" \
  https://app.shuttleglobal.com/c/api/payment_links

Step 3: Handle Token Expiration

Access tokens expire after 1 hour. When a request returns 401, use the refresh token to obtain a new access token via the token endpoint, then retry the request. See the OAuth 2.0 Introduction for the complete token refresh flow.