Authentication

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

Complete Examples:

// JavaScript with fetch
const response = await fetch('https://app.shuttleglobal.com/c/api/payment_links', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

// Node.js with axios
const axios = require('axios');

const response = await axios.get('https://app.shuttleglobal.com/c/api/payment_links', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

# Python with requests
import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://app.shuttleglobal.com/c/api/payment_links',
    headers=headers
)

# curl examples
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. Implement token refresh logic:

// Example token refresh logic
async function makeAuthenticatedRequest(url, options = {}) {
  try {
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${currentAccessToken}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    if (response.status === 401) {
      // Token expired, refresh and retry
      await refreshAccessToken();
      return makeAuthenticatedRequest(url, options);
    }

    return response;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

For complete token refresh implementation, see the OAuth 2.0 Introduction.