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/jsoncurl -H "Authorization: Bearer at_1234_h480djs93hd8" \
https://app.shuttleglobal.com/c/api/payment_linksStep 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.