Authentication

The Waymaker One API uses a dual-authentication system supporting both internal Waymaker applications and external API customers.

Authentication Methods

1. JWT Token Authentication (Recommended)

For applications with user sessions, use JWT tokens from the Waymaker authentication system.

const response = await fetch('https://api.waymakerone.com/v1/coordinate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${userToken}`,
    'Content-Type': 'application/json',
    'x-app-context': 'your-app-name'
  },
  body: JSON.stringify({
    messages: [{
      role: 'user',
      content: 'Help me create a strategy canvas for my startup'
    }]
  })
});

2. API Key Authentication

For server-to-server integrations and external applications.

const response = await fetch('https://api.waymakerone.com/v1/coordinate', {
  method: 'POST',
  headers: {
    'apikey': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{
      role: 'user',
      content: 'Analyze our customer journey for e-commerce'
    }]
  })
});

Authentication Flow

For Internal Waymaker Apps

Obtain User Token: Use your app's existing Supabase authentication
Include App Context: Add x-app-context header to identify your application
Make API Calls: Include the user token in the Authorization header

// Example for Waymaker Advisor integration
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.VITE_SUPABASE_URL!,
  process.env.VITE_SUPABASE_ANON_KEY!
);

const { data: { session } } = await supabase.auth.getSession();

if (session?.access_token) {
  const apiResponse = await fetch('https://api.waymakerone.com/v1/coordinate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${session.access_token}`,
      'Content-Type': 'application/json',
      'x-app-context': 'advisor'
    },
    body: JSON.stringify(request)
  });
}

For External Applications

Get API Key: Register at api.waymakerone.com/register
Choose Tier: Select appropriate usage tier (see Rate Limiting)
Secure Storage: Store API key securely (never in client-side code)
Make Requests: Include API key in requests

import requests

headers = {
    'apikey': 'your-api-key',
    'Content-Type': 'application/json'
}

data = {
    'messages': [{
        'role': 'user',
        'content': 'Help me analyze our business model'
    }],
    'userContext': {
        'industry': 'technology',
        'businessStage': 'growth'
    }
}

response = requests.post(
    'https://api.waymakerone.com/v1/coordinate',
    headers=headers,
    json=data
)

Request Headers

Required Headers

Header	Description	Example
`Authorization` or `apikey`	Authentication credentials	`Bearer <token>` or API key
`Content-Type`	Request content type	`application/json`

Optional Headers

Header	Description	Example
`x-app-context`	Application identifier	`advisor`, `commander`, `external`
`x-client-info`	Client information	`waymaker-js-sdk/1.0.0`

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid authentication credentials",
  "code": "AUTH_INVALID_TOKEN"
}

403 Forbidden

{
  "error": "forbidden",
  "message": "Insufficient permissions for this operation",
  "code": "AUTH_INSUFFICIENT_PERMISSIONS"
}

429 Rate Limited

{
  "error": "rate_limited",
  "message": "Rate limit exceeded for your tier",
  "code": "RATE_LIMIT_EXCEEDED",
  "resetTime": "2025-07-12T15:30:00Z"
}

Security Best Practices

API Key Management

Never expose API keys in client-side code or public repositories
Rotate keys regularly for enhanced security
Use environment variables for key storage
Implement proper error handling for authentication failures

JWT Token Handling

Validate tokens before making API calls
Handle token expiration with refresh logic
Use secure storage for tokens in client applications
Include app context for proper routing and analytics

Rate Limiting

Monitor usage against your tier limits
Implement exponential backoff for rate-limited requests
Cache responses when appropriate to reduce API calls
Consider upgrading tiers for higher usage needs

Development vs Production

Development Mode

Uses Supabase anonymous keys for testing
Relaxed rate limiting for development
Additional debugging headers available

Production Mode

Requires valid authentication tokens
Full rate limiting enforcement
Enhanced security validation

Migration Guide

From Direct Edge Functions

If you're currently using Waymaker edge functions directly:

// OLD: Direct edge function call
const response = await supabase.functions.invoke('one-framework', {
  body: { messages: [...] }
});

// NEW: Waymaker One API
const response = await fetch('https://api.waymakerone.com/v1/coordinate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
    'x-app-context': 'your-app'
  },
  body: JSON.stringify({
    messages: [...],
    preferences: { forceAgent: 'framework' }
  })
});