Getting Started with Changemaker

This guide will help you understand the basics of authenticating with the Changemaker platform and making your first API calls.

Authentication

All API requests require authentication using Supabase session cookies. When you log in through the web interface, a session cookie is automatically set.

Making Authenticated Requests

Include credentials in your fetch requests to send the session cookie:

fetch('https://changemaker.im/api/user/workspaces', {
  method: 'GET',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Session Management

Sessions are managed by Supabase and are valid for a configurable duration. If you receive a 401 Unauthorized response, your session has expired and you need to log in again.

Workspace Context

Most API operations require a workspace context. Public endpoints use the format:

/api/user/workspaces           # List user's workspaces
/api/workspaces/{slug}         # Get workspace details
/api/workspaces/{slug}/...     # Workspace-specific operations

Switching Workspaces

Users can belong to multiple workspaces. To switch context:

POST /api/auth/switch-workspace
Content-Type: application/json

{
  "workspaceId": "uuid-of-workspace"
}

Making Your First API Call

Let's retrieve your list of workspaces:

// Fetch user's workspaces
const response = await fetch('/api/user/workspaces', {
  credentials: 'include'
});

if (!response.ok) {
  throw new Error('Failed to fetch workspaces');
}

const { workspaces } = await response.json();
console.log('My workspaces:', workspaces);

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

// Error response format
{
  "error": "Resource not found",
  "details": "Challenge with ID abc123 does not exist"
}

Common Status Codes

• 200 OK - Request succeeded
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request data or parameters
• 401 Unauthorized - Authentication required or session expired
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource does not exist
• 500 Internal Server Error - Server error occurred

Error Handling Example

try {
  const response = await fetch('/api/workspaces/my-workspace/challenges', {
    credentials: 'include'
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        // Redirect to login
        window.location.href = '/auth/signin';
        break;
      case 403:
        console.error('Access denied:', error.error);
        break;
      case 404:
        console.error('Resource not found:', error.error);
        break;
      default:
        console.error('API error:', error.error);
    }

    return;
  }

  const data = await response.json();
  console.log('Challenges:', data.challenges);
} catch (error) {
  console.error('Network error:', error);
}

Rate Limiting

API requests are rate limited to ensure fair usage. Rate limit information is included in response headers:

• X-RateLimit-Limit - Maximum requests per window
• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Time when the rate limit resets (Unix timestamp)

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait for the reset time before making additional requests.

Next Steps