Basic API Documentation - API Mobile Digital

📚 Overview

Simple & Quick - The Basic API provides straightforward authentication for developers who want to get started quickly without the complexity of OAuth2.

What is the Basic API?

The Basic API uses standard authentication methods that are simple to implement and understand. This is the original API authentication method, maintained for backwards compatibility and ease of use.

When to Use Basic API

Quick prototyping - Get up and running in minutes
Simple integrations - Straightforward authentication without token management
Legacy support - Existing integrations that rely on this method
Internal tools - Simple scripts and internal applications

Recommendation: For production applications, we recommend using OAuth2 API for enhanced security with time-limited tokens and granular scopes.

🔑 Authentication Methods

Method 1: API Key in Query Parameters

Pass your API key directly in the URL as a query parameter:

GET https://api.mobile.digital/endpoint?api_key=YOUR_API_KEY

Method 2: Custom Header

Include your API key in a custom header:

GET https://api.mobile.digital/endpoint
X-API-Key: YOUR_API_KEY

Method 3: HTTP Basic Authentication

Use standard HTTP Basic Auth with your username and password:

GET https://api.mobile.digital/endpoint
Authorization: Basic base64(username:password)

Security Note: Always use HTTPS when transmitting API keys. Never expose API keys in client-side JavaScript or public repositories.

Getting Your Credentials

Your API credentials are available from:

Your account dashboard
Your system administrator
Initial account setup email

🚀 Getting Started

Step 1: Obtain Your API Key

Contact your administrator or check your account dashboard to obtain your API key.

Step 2: Test the API Explorer

Visit the Basic API Explorer
Click the Authorize button
Enter your API credentials
Try out the available endpoints

Step 3: Make Your First Call

Test with a simple API call using cURL:

curl -X GET 'https://api.mobile.digital/test?api_key=YOUR_API_KEY'

Success! If you receive a 200 OK response, your API key is working correctly.

💻 Code Examples

Python Example - Query Parameter

import requests

api_key = "your_api_key_here"
base_url = "https://api.mobile.digital"

# Example: Send SMS
endpoint = f"{base_url}/sendSMS"
params = {
    "api_key": api_key,
    "recipient": "+61400000000",
    "message": "Hello from Python!"
}

response = requests.get(endpoint, params=params)
print(response.json())

Python Example - Header Authentication

import requests

api_key = "your_api_key_here"
base_url = "https://api.mobile.digital"

# Example: Send SMS with header auth
endpoint = f"{base_url}/sendSMS"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}
data = {
    "recipient": "+61400000000",
    "message": "Hello from Python with headers!"
}

response = requests.post(endpoint, headers=headers, json=data)
print(response.json())

cURL Example - Query Parameter

curl -X POST 'https://api.mobile.digital/sendSMS?api_key=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "+61400000000",
    "message": "Hello from cURL!"
  }'

cURL Example - Header Authentication

curl -X POST 'https://api.mobile.digital/sendSMS' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": "+61400000000",
    "message": "Hello from cURL with headers!"
  }'

PHP Example

<?php
$api_key = "your_api_key_here";
$base_url = "https://api.mobile.digital";

// Example: Send SMS
$endpoint = "$base_url/sendSMS";
$data = [
    "recipient" => "+61400000000",
    "message" => "Hello from PHP!"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint . "?api_key=" . urlencode($api_key));
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Response ($http_code): $response\n";
?>

Node.js Example

const axios = require('axios');

const apiKey = 'your_api_key_here';
const baseUrl = 'https://api.mobile.digital';

// Example: Send SMS with header auth
async function sendSMS() {
    try {
        const response = await axios.post(
            `${baseUrl}/sendSMS`,
            {
                recipient: '+61400000000',
                message: 'Hello from Node.js!'
            },
            {
                headers: {
                    'X-API-Key': apiKey,
                    'Content-Type': 'application/json'
                }
            }
        );

        console.log('Response:', response.data);
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}

sendSMS();

JavaScript (Fetch API)

const apiKey = 'your_api_key_here';
const baseUrl = 'https://api.mobile.digital';

// Example: Send SMS
fetch(`${baseUrl}/sendSMS`, {
    method: 'POST',
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        recipient: '+61400000000',
        message: 'Hello from JavaScript!'
    })
})
.then(response => response.json())
.then(data => console.log('Response:', data))
.catch(error => console.error('Error:', error));

🔄 Migration to OAuth2

Why Migrate to OAuth2?

While the Basic API is simple and functional, OAuth2 offers several advantages:

Feature	Basic API	OAuth2 API
Token Expiration	Never expires	1 hour (automatically renewable)
Granular Permissions	All-or-nothing access	Scope-based access control
Token Revocation	Manual key rotation required	Instant token revocation
Security	Static credentials	Time-limited tokens + secret storage
Audit Trail	Limited	Detailed token usage logs

Migration Steps

Get OAuth2 Credentials
- Request client_id and client_secret from your administrator
Review Documentation
- Read the OAuth2 API Documentation
- Understand the Client Credentials flow
Update Your Code
- Replace API key with OAuth2 token acquisition
- Add token caching and refresh logic
Test in Sandbox
- Use the OAuth2 API Explorer
- Validate with test credentials first
Deploy Gradually
- Run both methods in parallel during transition
- Monitor and validate OAuth2 integration
- Retire Basic API credentials once stable

Side-by-Side Comparison

Basic API:

curl -X POST 'https://api.mobile.digital/sendSMS?api_key=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"recipient": "+61400000000", "message": "Hello!"}'

OAuth2 API:

# Step 1: Get token (cache this for 1 hour)
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' \
  | jq -r '.access_token')

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

Need Help? Check out our Token Generator Scripts to simplify OAuth2 token management.

✨ Best Practices

Security

✅ Always use HTTPS, never HTTP
✅ Store API keys in environment variables, not in code
✅ Use header authentication instead of query parameters when possible
✅ Rotate API keys periodically
✅ Never commit API keys to version control
✅ Use separate keys for development/staging/production

Error Handling

✅ Check HTTP status codes (200 = success, 401 = unauthorized, etc.)
✅ Implement retry logic with exponential backoff
✅ Log errors with context for debugging
✅ Handle network timeouts gracefully

Performance

✅ Reuse HTTP connections when making multiple requests
✅ Implement request rate limiting to avoid throttling
✅ Cache API responses when appropriate
✅ Use compression (Accept-Encoding: gzip)