🔐 OAuth2 API Documentation

📚 Overview

What is OAuth2?

OAuth2 is an industry-standard protocol for authorization. The Client Credentials flow is designed for machine-to-machine authentication where your application authenticates using a client ID and client secret to obtain an access token.

Key Benefits

• Secure - Tokens are time-limited and can be revoked
• Standard - Industry-wide protocol, works with most HTTP clients
• Stateless - No session management required
• Scoped - Granular permissions with scope-based access control
• Auto-managed - Swagger UI handles token refresh automatically

🔑 Authentication Flow

Step 1: Get Your Credentials

You'll receive from your account administrator:

• client_id - Your unique client identifier
• client_secret - Your secret key (keep this confidential!)

Step 2: Exchange Credentials for Token

Send a POST request to the token endpoint with your credentials to receive an access token.

Step 3: Use Token in API Requests

Include the access token in the Authorization header of all API requests as a Bearer token.

🎫 Getting an Access Token

Token Endpoint

POST https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/oauth2/token

Request Format

Headers:

• Authorization: Basic <base64(client_id:client_secret)>
• Content-Type: application/x-www-form-urlencoded

Body (x-www-form-urlencoded):

• grant_type=client_credentials (required)
• scope=read write admin (optional, space-separated scopes)

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write admin"
}

🚀 Using Access Tokens

Making Authenticated Requests

Include the access token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example API Call

POST https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/sendSMS
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "recipient": "+61400000000",
  "message": "Hello from OAuth2!"
}

Token Expiration

Access tokens expire after 1 hour (3600 seconds). When a token expires:

• API returns HTTP 401 Unauthorized
• Request a new token using the same process
• No need to invalidate old tokens - they expire automatically

💻 Code Examples

Python Example

import requests
import base64
import json

# Your credentials
client_id = "your_client_id"
client_secret = "your_client_secret"

# Encode credentials for Basic Auth
credentials = f"{client_id}:{client_secret}"
encoded_credentials = base64.b64encode(credentials.encode()).decode()

# Get access token
token_url = "https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/oauth2/token"
token_headers = {
    "Authorization": f"Basic {encoded_credentials}",
    "Content-Type": "application/x-www-form-urlencoded"
}
token_data = {
    "grant_type": "client_credentials",
    "scope": "read write admin"
}

response = requests.post(token_url, headers=token_headers, data=token_data)
token_response = response.json()
access_token = token_response["access_token"]

print(f"Access Token: {access_token}")

# Use token to make API call
api_url = "https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/sendSMS"
api_headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}
api_data = {
    "recipient": "+61400000000",
    "message": "Hello from Python!"
}

api_response = requests.post(api_url, headers=api_headers, json=api_data)
print(f"API Response: {api_response.json()}")

cURL Example

# Step 1: Get access token
curl -X POST 'https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/oauth2/token' \
  -H 'Authorization: Basic $(echo -n "client_id:client_secret" | base64)' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=read write admin'

# Step 2: Use token in API call
curl -X POST 'https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/sendSMS' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"recipient": "+61400000000", "message": "Hello!"}'

PHP Example

<?php
$client_id = "your_client_id";
$client_secret = "your_client_secret";

// Get access token
$credentials = base64_encode("$client_id:$client_secret");
$token_url = "https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/oauth2/token";

$ch = curl_init($token_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Basic $credentials",
    "Content-Type: application/x-www-form-urlencoded"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, "grant_type=client_credentials&scope=read write admin");

$response = curl_exec($ch);
$token_data = json_decode($response, true);
$access_token = $token_data['access_token'];

curl_close($ch);

// Use token for API call
$api_url = "https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/sendSMS";
$api_data = json_encode([
    "recipient" => "+61400000000",
    "message" => "Hello from PHP!"
]);

$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $access_token",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $api_data);

$api_response = curl_exec($ch);
echo "API Response: $api_response\n";

curl_close($ch);
?>

Node.js Example

const axios = require('axios');

const clientId = 'your_client_id';
const clientSecret = 'your_client_secret';

// Get access token
async function getAccessToken() {
    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

    const response = await axios.post(
        'https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/oauth2/token',
        'grant_type=client_credentials&scope=read write admin',
        {
            headers: {
                'Authorization': `Basic ${credentials}`,
                'Content-Type': 'application/x-www-form-urlencoded'
            }
        }
    );

    return response.data.access_token;
}

// Use token for API call
async function sendSMS() {
    const accessToken = await getAccessToken();

    const response = await axios.post(
        'https://ah1ta9hc59.execute-api.ap-southeast-2.amazonaws.com/prod/sendSMS',
        {
            recipient: '+61400000000',
            message: 'Hello from Node.js!'
        },
        {
            headers: {
                'Authorization': `Bearer ${accessToken}`,
                'Content-Type': 'application/json'
            }
        }
    );

    console.log('API Response:', response.data);
}

sendSMS().catch(console.error);

🔐 Available Scopes

Core Scopes

Gifting Scopes (Optional Add-on)

Requesting Multiple Scopes

Request multiple scopes by separating them with spaces:

scope=read write admin gifting:send gifting:links

⚠️ Error Handling

Common Errors

Error Response Format

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

🧪 Testing Your Integration

Using Swagger UI

1. Visit OAuth2 API Explorer
2. Click the Authorize button (🔓 lock icon)
3. Under ClientCredentials section:
   • Check the scopes you need
   • Enter your client_id and client_secret
   • Click Authorize
4. Try the /test-oauth2 endpoint to validate

Quick Token Generator

For command-line testing, use our token generator scripts:

• 📖 Token Generator Scripts Guide
• 🐍 Python script with interactive prompts
• 🐚 Bash script for quick terminal use