Skip to content

Authentication

The UnaCODE API uses development token authentication for secure access to all endpoints.

Quick Start

# Include token in Authorization header
curl -H "Authorization: Bearer dev_token_placeholder" \
     https://v5.unacode.mrmaidenos.com/api/v1/orchestrators

Authentication Methods

Development Token (Current)

For development and testing, use the development token:

Authorization: Bearer dev_token_placeholder

Production Authentication (Coming Soon)

Production will use JWT tokens with proper user authentication:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Token Validation

All API endpoints validate the authorization token. Missing or invalid tokens return:

{
  "success": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED"
}

User Context

The authentication system provides user context for: - Usage tracking and billing - Permission-based access control - Personalized responses and history - Rate limiting and quotas

WebSocket Authentication

Method 1: Connection Headers

const ws = new WebSocket('ws://localhost:8765', [], {
  headers: {
    'Authorization': 'Bearer dev_token_placeholder'
  }
});

Method 2: Auth Message After Connection

ws.send(JSON.stringify({
  type: 'auth',
  token: 'dev_token_placeholder'
}));

Rate Limiting

Authentication enables per-user rate limiting: - 60 requests per minute per authenticated user - Burst limit: 10 requests - WebSocket connections: 5 concurrent per user

Permission Levels

User Permissions

  • Access to orchestrators and teams
  • Personal usage statistics
  • Own chat conversations
  • Basic system information

Admin Permissions

  • System administration endpoints
  • User management access
  • System configuration changes
  • Full analytics and logs

Security Best Practices

Development

  • Use development tokens only in local development
  • Never commit tokens to version control
  • Rotate tokens periodically
  • Implement proper JWT authentication
  • Use HTTPS for all API communication
  • Store tokens securely (e.g., secure cookies)
  • Implement token refresh mechanisms
  • Add multi-factor authentication for admin access

Error Handling

Invalid Token

{
  "success": false,
  "error": "Invalid authentication token",
  "code": "INVALID_TOKEN"
}

Expired Token

{
  "success": false,
  "error": "Authentication token has expired", 
  "code": "TOKEN_EXPIRED"
}

Insufficient Permissions

{
  "success": false,
  "error": "Insufficient permissions for this operation",
  "code": "FORBIDDEN"
}

Integration Examples

JavaScript/Fetch

const apiCall = async (endpoint, options = {}) => {
  const response = await fetch(`https://v5.unacode.mrmaidenos.com/api/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': 'Bearer dev_token_placeholder',
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    throw new Error(`API call failed: ${response.statusText}`);
  }

  return response.json();
};

// Usage
const orchestrators = await apiCall('/orchestrators');

Python/Requests

import requests

class UnaCODEClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def get_orchestrators(self):
        response = requests.get(
            f'{self.base_url}/orchestrators',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
client = UnaCODEClient(
    'https://v5.unacode.mrmaidenos.com/api/v1',
    'dev_token_placeholder'
)
orchestrators = client.get_orchestrators()

Generated on 2025-08-12 14:48:04