Admin API

The Admin API provides administrative functions for managing users, NPCs, bot tokens, MCP servers, and system monitoring in PadawanForge.

Base Paths

/api/admin/ - Administrative functions
/api/debug/ - Debug and monitoring tools
/api/users/ - User management (admin only)

Authentication & Role-Based Access

Admin endpoints use role-based access control with the following hierarchy:

Role Levels & Access

Guest (Level 0): Demo system and documentation access only
Padawan (Level 1): Browse-only access to players, NPCs, and games
Game Master (Level 2): Can create/remove NPCs and games
Guild Leader (Level 3): Currently unused role, no additional permissions
System Admin (Level 4): Full system configuration access

Permission Requirements

Different endpoints require specific permissions rather than just role levels.

Bot Token Management

List Bot Tokens

GET /api/admin/bot-tokens

Authentication: System Admin required (admin.config permission)

Response:

{
  "tokens": [
    {
      "id": "token_uuid",
      "name": "Production Bot",
      "description": "Main production bot token",
      "provider": "openai",
      "model": "gpt-4",
      "status": "active",
      "lastUsed": "2024-01-20T15:30:00Z",
      "usageCount": 1250,
      "createdAt": "2024-01-10T10:00:00Z",
      "expiresAt": "2024-07-10T10:00:00Z"
    }
  ]
}

Create Bot Token

POST /api/admin/bot-tokens

Authentication: System Admin required (admin.config permission)

Request Body:

{
  "name": "Development Bot",
  "description": "Bot token for development environment",
  "provider": "anthropic",
  "model": "claude-3-sonnet",
  "apiKey": "sk-ant-api03-...",
  "maxTokens": 1000,
  "temperature": 0.7,
  "rateLimit": {
    "requests": 100,
    "window": "1h"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "new_token_uuid",
    "name": "Development Bot",
    "provider": "anthropic",
    "model": "claude-3-sonnet",
    "status": "active",
    "createdAt": "2024-01-20T16:00:00Z"
  }
}

Get Bot Token

GET /api/admin/bot-tokens/[id]

Authentication: Admin required

Response:

{
  "id": "token_uuid",
  "name": "Production Bot",
  "description": "Main production bot token",
  "provider": "openai",
  "model": "gpt-4",
  "apiKey": "sk-...***masked***",
  "maxTokens": 1000,
  "temperature": 0.7,
  "status": "active",
  "usage": {
    "totalRequests": 1250,
    "successfulRequests": 1200,
    "failedRequests": 50,
    "averageResponseTime": 850,
    "lastDay": {
      "requests": 45,
      "tokens": 12500
    }
  },
  "rateLimit": {
    "requests": 1000,
    "window": "1h",
    "remaining": 955
  },
  "createdAt": "2024-01-10T10:00:00Z"
}

Test Bot Token

POST /api/admin/bot-tokens/[id]/test

Authentication: Admin required

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "responseTime": 650,
    "testResponse": "Test response from AI provider",
    "model": "gpt-4",
    "tokens": {
      "prompt": 15,
      "completion": 25,
      "total": 40
    },
    "testedAt": "2024-01-20T16:15:00Z"
  }
}

MCP Server Management

List MCP Servers

GET /api/admin/mcp-servers

Authentication: Admin required

Response:

{
  "servers": [
    {
      "id": "server_uuid",
      "name": "Game Analytics Server",
      "type": "analytics",
      "url": "https://analytics.example.com/mcp",
      "status": "connected",
      "capabilities": ["analytics", "reporting", "metrics"],
      "lastPing": "2024-01-20T15:45:00Z",
      "version": "1.2.0"
    }
  ]
}

Create MCP Server

POST /api/admin/mcp-servers

Authentication: System Admin required (admin.config permission)

Request Body:

{
  "name": "Content Generation Server",
  "type": "content",
  "url": "https://content.example.com/mcp",
  "apiKey": "mcp_api_key",
  "capabilities": ["statement_generation", "npc_responses"],
  "config": {
    "timeout": 30000,
    "retries": 3,
    "healthCheckInterval": 300
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "new_server_uuid",
    "name": "Content Generation Server",
    "type": "content",
    "status": "connecting",
    "createdAt": "2024-01-20T16:30:00Z"
  }
}

Get Server Suggestions

GET /api/admin/mcp-servers/suggestions

Authentication: Admin required

Response:

{
  "suggestions": [
    {
      "name": "Educational Content Server",
      "type": "content",
      "description": "Specialized in generating educational statements",
      "provider": "EduTech Solutions",
      "capabilities": ["statement_generation", "fact_checking"]
    }
  ]
}

Test MCP Server

POST /api/admin/mcp-servers/[id]/test

Authentication: Admin required

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "responseTime": 250,
    "capabilities": ["analytics", "reporting"],
    "version": "1.2.0",
    "lastPing": "2024-01-20T16:45:00Z"
  }
}

User Management

List Users

GET /api/users

Authentication: Admin required

Query Parameters:

page (optional) - Page number
limit (optional) - Items per page
role (optional) - Filter by role
status (optional) - Filter by status: active, suspended, deleted
search (optional) - Search by username or email

Response:

{
  "items": [
    {
      "uuid": "user_uuid",
      "username": "PlayerName",
      "email": "player@example.com",
      "level": 5,
      "experience": 1250,
      "role": "padawan",
      "status": "active",
      "lastActive": "2024-01-20T15:30:00Z",
      "joinedAt": "2024-01-10T10:00:00Z",
      "stats": {
        "gamesPlayed": 45,
        "averageScore": 680,
        "totalPlayTime": 2700
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1250,
    "pages": 25
  }
}

Get User Statistics

GET /api/users/stats

Authentication: Admin required

Response:

{
  "overview": {
    "totalUsers": 1250,
    "activeUsers": 980,
    "newUsersThisMonth": 150,
    "retentionRate": 0.75
  },
  "demographics": {
    "byRole": {
      "guest": 50,
      "padawan": 1000,
      "game_master": 180,
      "guild_leader": 15,
      "system_admin": 5
    },
    "byLevel": {
      "1-5": 600,
      "6-10": 400,
      "11-20": 200,
      "21+": 50
    }
  },
  "activity": {
    "dailyActiveUsers": 350,
    "weeklyActiveUsers": 650,
    "monthlyActiveUsers": 980,
    "averageSessionTime": 420
  }
}

Debug & Monitoring

Database Debug

GET /api/debug/database

Authentication: System Admin required

Response:

{
  "status": "healthy",
  "connections": {
    "active": 15,
    "idle": 5,
    "total": 20
  },
  "performance": {
    "averageQueryTime": 25,
    "slowQueries": 2,
    "errorRate": 0.001
  },
  "tables": [
    {
      "name": "players",
      "rowCount": 1250,
      "size": "2.5MB",
      "lastUpdated": "2024-01-20T15:45:00Z"
    }
  ]
}

KV Storage Debug

GET /api/debug/kv

Authentication: System Admin required

Response:

{
  "status": "healthy",
  "metrics": {
    "totalKeys": 3500,
    "usedStorage": "45MB",
    "operations": {
      "reads": 15000,
      "writes": 2500,
      "deletes": 150
    }
  },
  "namespaces": [
    {
      "name": "sessions",
      "keys": 1200,
      "size": "15MB"
    },
    {
      "name": "cache",
      "keys": 2300,
      "size": "30MB"
    }
  ]
}

OAuth Debug

GET /api/debug/oauth

Authentication: System Admin required

Response:

{
  "providers": [
    {
      "provider": "google",
      "status": "healthy",
      "configurations": {
        "clientIdConfigured": true,
        "clientSecretConfigured": true,
        "redirectUriConfigured": true
      },
      "recentActivity": {
        "successfulLogins": 150,
        "failedLogins": 5,
        "tokenRefreshes": 45
      }
    }
  ]
}

System Cleanup

POST /api/debug/cleanup

Authentication: System Admin required

Request Body:

{
  "cleanupType": "expired_sessions" | "old_logs" | "temp_files" | "all",
  "olderThan": "7d",
  "dryRun": false
}

Response:

{
  "success": true,
  "data": {
    "cleanupType": "expired_sessions",
    "itemsCleaned": 150,
    "spaceFreed": "5MB",
    "executionTime": 2500,
    "dryRun": false
  }
}

Health Check

System Health

GET /api/health
HEAD /api/health

No authentication required

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-20T16:00:00Z",
  "services": {
    "database": {
      "status": "healthy",
      "responseTime": 15
    },
    "kv": {
      "status": "healthy",
      "responseTime": 8
    },
    "chatLobby": {
      "status": "healthy",
      "activeConnections": 25
    },
    "roomManager": {
      "status": "healthy",
      "activeRooms": 8
    },
    "workflows": {
      "status": "healthy",
      "runningWorkflows": 3
    },
    "files": {
      "status": "healthy",
      "storageUsed": "250MB"
    }
  },
  "uptime": 86400,
  "version": "1.2.6"
}

Error Responses

Insufficient Permissions

{
  "error": "Access denied",
  "details": "Guild Leader or System Admin role required"
}

Resource Not Found

{
  "error": "Bot token not found",
  "details": "No bot token found with the provided ID"
}

Configuration Error

{
  "error": "Invalid configuration",
  "details": "API key is invalid or expired"
}

Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "details": "Too many test requests. Try again in 1 hour.",
  "retryAfter": 3600
}

Rate Limits

Bot token operations: 50 per hour per admin
MCP server operations: 30 per hour per admin
Debug endpoints: 20 per hour per admin
System cleanup: 5 per day per admin
Health checks: No limit

Security Notes

API Key Masking: API keys are always masked in responses
Audit Logging: All admin actions are logged with user attribution
Permission Checks: Role-based access control enforced on all endpoints
Rate Limiting: Prevents abuse of resource-intensive operations
Encryption: Sensitive configuration data encrypted at rest

Authentication API →