Admin API

The Admin API provides administrative endpoints for managing users, organizations, and system-wide settings. These endpoints require admin role access.

Authentication

All admin endpoints require authentication with an admin-privileged account. Include your session token in the request headers:

Authorization: Bearer <session_token>

Authorization

Access to admin endpoints is restricted to users with the admin role. Attempting to access these endpoints without proper permissions will result in a 403 Forbidden response.

Base URL

/api/admin

Endpoints Overview

Response Format

All responses follow a consistent JSON structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Responses

Error responses include descriptive codes and messages:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Admin access required"
  }
}

Error Codes

Rate Limits

Admin endpoints have higher rate limits due to their administrative nature:

• 500 requests per minute per admin user
• 5000 requests per hour per admin user

Audit Logging

All admin actions are automatically logged for security and compliance:

• User who performed the action
• Timestamp
• Action type (CREATE, UPDATE, DELETE)
• Resource affected
• Changes made (for updates)

SDK Example

import { createAdminClient } from '@/lib/admin/client';

const admin = createAdminClient();

// List all users
const users = await admin.users.list({
  page: 1,
  limit: 50,
  search: 'john@example.com'
});

// Create a new organization
const org = await admin.organizations.create({
  name: 'Acme Corp',
  slug: 'acme-corp',
  plan: 'enterprise'
});