admin

Admin API Reference

API reference for super admin endpoints, roles, permissions, and impersonation features.

Overview

The Admin API provides endpoints for platform administrators to manage API keys, monitor usage, configure LLM providers, and impersonate organisations. These endpoints require authenticated admin users with appropriate role permissions.

Authentication

All admin endpoints require session-based authentication through Supabase Auth. Admin users must be logged in via the web dashboard.

Role Hierarchy

Role	Description	Permissions
`viewer`	Read-only access to admin dashboard	View usage, costs, organisations
`admin`	Standard admin access	All viewer permissions + manage API keys, models
`super_admin`	Full platform access	All admin permissions + impersonation, system settings

Role Assignment

Admin roles are determined by:

Super admin emails - Explicitly listed platform owner emails
App metadata - app_metadata.admin_role, which only the service role can set (user_metadata is never trusted)

Rate Limiting

All admin endpoints are rate limited to prevent abuse:

Operation Type	Limit	Window
Read operations	60 requests	1 minute
Write operations	30 requests	1 minute
Sensitive operations	10 requests	1 minute
Heavy operations	5 requests	1 minute

Rate limit headers are included in all responses:

text

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704067200

When rate limited, you'll receive a 429 Too Many Requests response.

API Keys Management

List API Keys

http

GET /api/admin/api-keys

Query Parameters:

Parameter	Type	Description
`provider`	string	Filter by provider (openai, anthropic, google, screenshotone, resend)
`active_only`	boolean	Only return active keys

Response:

JSON

{
  "data": {
    "apiKeys": [
      {
        "id": "uuid",
        "provider": "openai",
        "keyName": "Production Key",
        "keyPrefix": "sk-proj-...",
        "isActive": true,
        "isDefault": true,
        "rateLimitTier": "standard",
        "usageCount": 1250,
        "lastUsedAt": "2024-01-10T12:00:00Z",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "count": 1
  }
}

Create API Key

http

POST /api/admin/api-keys

Request Body:

JSON

{
  "provider": "openai",
  "keyName": "Production Key",
  "apiKey": "sk-proj-xxxxx",
  "isDefault": true,
  "rateLimitTier": "standard"
}

Providers: openai, anthropic, google, screenshotone, resend

Rate Limit Tiers: standard, high, unlimited

Get Single API Key

http

GET /api/admin/api-keys/:id

Update API Key

http

PATCH /api/admin/api-keys/:id

Request Body:

JSON

{
  "keyName": "Updated Key Name",
  "isActive": false,
  "isDefault": true,
  "rateLimitTier": "high"
}

Delete API Key

http

DELETE /api/admin/api-keys/:id

Impersonation

Super admins can impersonate organisations to view the dashboard as an organisation owner. This is useful for debugging and customer support.

Start Impersonation

http

POST /api/admin/impersonate

Required Role: super_admin

Request Body:

JSON

{
  "organisation_id": "uuid"
}

Response:

JSON

{
  "success": true,
  "message": "Now impersonating Acme Tours",
  "data": {
    "organisation_id": "uuid",
    "organisation_name": "Acme Tours",
    "expires_at": "2024-01-10T13:00:00Z"
  }
}

Impersonation sessions automatically expire after 1 hour.

Check Impersonation Status

http

GET /api/admin/impersonate

Required Role: super_admin

Response when impersonating:

JSON

{
  "impersonating": true,
  "data": {
    "organisation_id": "uuid",
    "organisation_name": "Acme Tours",
    "owner_email": "owner@acmetours.com",
    "started_at": "2024-01-10T12:00:00Z",
    "expires_at": "2024-01-10T13:00:00Z"
  }
}

Response when not impersonating:

JSON

{
  "impersonating": false
}

End Impersonation

http

DELETE /api/admin/impersonate

Required Role: super_admin

Response:

JSON

{
  "success": true,
  "message": "Impersonation ended"
}

LLM Settings

Get Settings

http

GET /api/admin/settings

Response:

JSON

{
  "data": {
    "default_provider": "openai",
    "default_model": "gpt-4o",
    "available_providers": ["openai", "anthropic", "google"]
  }
}

Update Settings

http

PUT /api/admin/settings

Required Role: admin or higher

Request Body:

JSON

{
  "default_provider": "anthropic",
  "default_model": "claude-3-opus-20240229",
  "available_providers": ["openai", "anthropic"]
}

Plan Limits

Get Plan Limits

http

GET /api/admin/plan-limits

Response:

JSON

{
  "data": [
    {
      "tier": "starter",
      "llm_txt_page_limit": 50,
      "monthly_summary_limit": 25,
      "can_select_provider": false
    },
    {
      "tier": "basic",
      "llm_txt_page_limit": 100,
      "monthly_summary_limit": 100,
      "can_select_provider": false
    },
    {
      "tier": "pro",
      "llm_txt_page_limit": 100,
      "monthly_summary_limit": 500,
      "can_select_provider": true
    }
  ]
}

Update Plan Limits

http

PUT /api/admin/plan-limits

Required Role: admin or higher

Request Body:

JSON

{
  "limits": [
    {
      "tier": "pro",
      "llm_txt_page_limit": 150,
      "monthly_summary_limit": 300,
      "can_select_provider": true
    }
  ]
}

Error Responses

All endpoints return the same error shape:

JSON

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Admin role required"
  }
}

Common Status Codes:

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Not authenticated
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limited
500	Internal Server Error

Audit Logging

All admin actions are logged for security and compliance:

User ID of the admin
Action type (create, read, update, delete)
Resource type and ID
Old and new values (for updates)
IP address and user agent
Timestamp

Audit logs are retained for 90 days and can be viewed by super admins.