Skip to main content

Authentication

The TimetableMaster API uses API key authentication to secure access to your timetable data. This guide will help you set up authentication for your applications.

Generating an API Key​

Step 1: Access Your Dashboard​

  1. Log in to your TimetableMaster account
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key

Step 2: Configure Your API Key​

  • Name: Give your API key a descriptive name (e.g., "School Website", "Mobile App")
  • Expires At: Optionally set an expiration date for enhanced security

Step 3: Save Your API Key​

Important: Copy and store your API key securely immediately after generation. For security reasons, you won't be able to view the full key again.

ttm_1234567890abcdef1234567890abcdef12345678

Using Your API Key​

Authentication Header​

Include your API key in the Authorization header of every API request:

Authorization: Bearer ttm_1234567890abcdef1234567890abcdef12345678

Example Request​

curl -H "Authorization: Bearer ttm_1234567890abcdef1234567890abcdef12345678" \
     -H "Content-Type: application/json" \
     https://www.timetablemaster.com/api/v1/timetables

Security Best Practices​

Environment Variables​

Store your API key in environment variables, never hardcode it in your application:

// ✅ Good
const apiKey = process.env.TIMETABLE_API_KEY;

// ❌ Bad
const apiKey = "ttm_1234567890abcdef..."; // Never do this!

Secure Storage​

  • Use secure environment variable management
  • Never commit API keys to version control
  • Rotate keys regularly for enhanced security
  • Use different keys for different environments (development, staging, production)

Network Security​

  • Always use HTTPS for API requests
  • Implement proper error handling to avoid exposing keys in logs
  • Consider IP restrictions if your application runs from fixed locations

Key Management​

Multiple Keys​

You can create multiple API keys for different purposes:

  • One for your website integration
  • Another for your mobile app
  • Separate keys for development and production

Key Rotation​

Regularly rotate your API keys for security:

  1. Generate a new API key
  2. Update your applications to use the new key
  3. Revoke the old key once all applications are updated

Revoking Keys​

If a key is compromised or no longer needed:

  1. Go to Settings → API Keys
  2. Find the key and click Revoke
  3. The key will be immediately deactivated

Authentication Errors​

Common Error Responses​

Missing Authorization Header​

{
  "success": false,
  "error": {
    "code": "MISSING_AUTH_HEADER",
    "message": "Authorization header is required. Format: Bearer YOUR_API_KEY"
  }
}

Invalid API Key​

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or not found"
  }
}

Expired API Key​

{
  "success": false,
  "error": {
    "code": "API_KEY_INVALID",
    "message": "The API key has expired"
  }
}

Rate Limit Exceeded​

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "resetTime": "2025-07-15T11:30:00Z"
  }
}

Testing Your Authentication​

Quick Test​

Test your API key with this simple request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://www.timetablemaster.com/api/v1/timetables

Expected Response​

If authentication is successful, you'll receive a response like:

{
  "success": true,
  "data": {
    "orgId": "your-org-id",
    "timetables": [...]
  },
  "timestamp": "2025-07-15T10:30:00Z"
}

Programming Language Examples​

JavaScript/Node.js​

const axios = require("axios");

const apiKey = process.env.TIMETABLE_API_KEY;
const baseURL = "https://www.timetablemaster.com/api/v1";

const api = axios.create({
  baseURL,
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
});

// Usage
async function getTimetables() {
  try {
    const response = await api.get("/timetables");
    return response.data;
  } catch (error) {
    console.error("API Error:", error.response.data);
    throw error;
  }
}

Python​

import requests
import os

API_KEY = os.getenv('TIMETABLE_API_KEY')
BASE_URL = 'https://www.timetablemaster.com/api/v1'

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

def get_timetables():
    response = requests.get(f'{BASE_URL}/timetables', headers=headers)

    if response.status_code == 200:
        return response.json()
    else:
        print(f'Error: {response.status_code} - {response.json()}')
        return None

PHP​

<?php
$apiKey = $_ENV['TIMETABLE_API_KEY'];
$baseUrl = 'https://www.timetablemaster.com/api/v1';

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

function getTimetables() {
    global $baseUrl, $headers;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . '/timetables');
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

    if ($httpCode === 200) {
        return json_decode($response, true);
    }

    return null;
}
?>

Next: Learn how to make your first API request and explore the available endpoints.