Skip to main content

Admin API

The Admin API provides 11 methods for platform administration. All methods in this section require the authenticated user to have the admin role. Non-admin users receive a "forbidden" error.

caution

These endpoints are restricted to admin users. The access token must belong to a user with role: 'admin'.

Methods​

MethodParametersReturnsDescription
adminListUsers(options?)options?: AdminListOptionsApiResponse<PaginatedResult<AdminUser>>Lists all platform users with pagination and filtering.
adminGetUser(userId)userId: stringApiResponse<AdminUser>Returns detailed profile and usage data for a single user.
adminUpdateUser(userId, updates)userId: string, updates: AdminUserUpdateApiResponse<AdminUser>Updates a user's profile, role, or status.
adminListProjects(options?)options?: AdminListOptionsApiResponse<PaginatedResult<AdminProject>>Lists all projects across the platform.
adminGetProject(projectId)projectId: stringApiResponse<AdminProject>Returns detailed configuration and usage data for a project.
adminUpdateProject(projectId, updates)projectId: string, updates: AdminProjectUpdateApiResponse<AdminProject>Updates a project's settings or status.
adminRegenerateApiKey(projectId)projectId: stringApiResponse<{ clientId: string; secretKey: string }>Regenerates API keys for a project. The old keys are immediately invalidated.
adminGetStats()--ApiResponse<SystemStats>Returns system-wide statistics (users, projects, transactions, revenue).
adminGetLogs(options?)options?: LogQueryOptionsApiResponse<SystemLog[]>Queries platform audit and error logs.
adminGetRateLimits(projectId?)projectId?: stringApiResponse<RateLimitInfo[]>Returns current rate-limit status, optionally scoped to a project.
adminClearRateLimits(projectId)projectId: stringApiResponse<{ cleared: boolean }>Clears rate-limit counters for a project.

Types​

AdminUser​

interface AdminUser {
  id: string;
  email?: string;
  walletAddress?: string;
  displayName?: string;
  avatarUrl?: string;
  role: 'user' | 'admin';
  status: 'active' | 'suspended' | 'banned';
  /** Number of projects owned by this user. */
  projectCount: number;
  /** Total API calls made by this user. */
  totalApiCalls: number;
  /** Last login timestamp. */
  lastLoginAt?: string;
  createdAt: string;
  updatedAt: string;
}

AdminUserUpdate​

interface AdminUserUpdate {
  displayName?: string;
  role?: 'user' | 'admin';
  status?: 'active' | 'suspended' | 'banned';
}

AdminProject​

interface AdminProject {
  id: string;
  name: string;
  ownerId: string;
  ownerEmail?: string;
  /** Masked client ID. */
  clientId: string;
  plan: 'free' | 'starter' | 'pro' | 'enterprise';
  status: 'active' | 'suspended' | 'archived';
  /** Enabled feature flags. */
  features: string[];
  /** API call count for the current billing period. */
  apiCallsThisPeriod: number;
  /** API call limit for the current plan. */
  apiCallLimit: number;
  /** Monthly revenue from this project. */
  monthlyRevenue?: string;
  createdAt: string;
  updatedAt: string;
}

AdminProjectUpdate​

interface AdminProjectUpdate {
  name?: string;
  plan?: 'free' | 'starter' | 'pro' | 'enterprise';
  status?: 'active' | 'suspended' | 'archived';
  apiCallLimit?: number;
}

AdminListOptions​

interface AdminListOptions {
  /** Search by email, name, or ID. */
  search?: string;
  /** Filter by status. */
  status?: string;
  /** Filter by role (users) or plan (projects). */
  role?: string;
  plan?: string;
  /** Sort field. */
  sortBy?: 'createdAt' | 'updatedAt' | 'apiCalls';
  /** Sort direction. */
  sortOrder?: 'asc' | 'desc';
  /** Page number (1-based). */
  page?: number;
  /** Items per page. Default 20, max 100. */
  pageSize?: number;
}

PaginatedResult<T>​

interface PaginatedResult<T> {
  items: T[];
  totalCount: number;
  page: number;
  pageSize: number;
  totalPages: number;
  hasMore: boolean;
}

SystemStats​

interface SystemStats {
  totalUsers: number;
  activeUsers30d: number;
  totalProjects: number;
  activeProjects30d: number;
  totalTransactions: number;
  transactions24h: number;
  totalApiCalls: number;
  apiCalls24h: number;
  totalRevenue: string;
  revenue30d: string;
  topChains: { chainId: string; chainName: string; transactionCount: number }[];
  /** Stats snapshot timestamp. */
  generatedAt: string;
}

SystemLog​

interface SystemLog {
  id: string;
  level: 'info' | 'warn' | 'error';
  /** Log category (e.g. "auth", "transaction", "webhook"). */
  category: string;
  message: string;
  /** Associated user ID, if applicable. */
  userId?: string;
  /** Associated project ID, if applicable. */
  projectId?: string;
  /** Additional metadata. */
  metadata?: Record<string, unknown>;
  timestamp: string;
}

LogQueryOptions​

interface LogQueryOptions {
  level?: 'info' | 'warn' | 'error';
  category?: string;
  userId?: string;
  projectId?: string;
  startDate?: string;
  endDate?: string;
  search?: string;
  limit?: number;
  cursor?: string;
}

RateLimitInfo​

interface RateLimitInfo {
  projectId: string;
  projectName: string;
  /** Endpoint or endpoint group. */
  endpoint: string;
  /** Current request count in the window. */
  currentCount: number;
  /** Maximum requests allowed in the window. */
  limit: number;
  /** Window duration in seconds. */
  windowSeconds: number;
  /** Time until the window resets (seconds). */
  resetsIn: number;
  /** Whether the project is currently rate-limited. */
  isLimited: boolean;
}

Examples​

List Users​

const res = await engine.adminListUsers({
  status: 'active',
  sortBy: 'createdAt',
  sortOrder: 'desc',
  page: 1,
  pageSize: 20,
});

if (res.success && res.data) {
  console.log(`Total users: ${res.data.totalCount}`);
  for (const user of res.data.items) {
    console.log(`${user.id} | ${user.email ?? user.walletAddress} | ${user.role} | API calls: ${user.totalApiCalls}`);
  }
}

Suspend a User​

const res = await engine.adminUpdateUser('user_xyz', {
  status: 'suspended',
});

if (res.success && res.data) {
  console.log(`User ${res.data.id} status: ${res.data.status}`);
}

View System Stats​

const res = await engine.adminGetStats();

if (res.success && res.data) {
  const s = res.data;
  console.log(`Users: ${s.totalUsers} (${s.activeUsers30d} active in 30d)`);
  console.log(`Projects: ${s.totalProjects} (${s.activeProjects30d} active in 30d)`);
  console.log(`Transactions 24h: ${s.transactions24h}`);
  console.log(`API calls 24h: ${s.apiCalls24h}`);
  console.log(`Revenue (30d): $${s.revenue30d}`);
}

Query Error Logs​

const res = await engine.adminGetLogs({
  level: 'error',
  category: 'transaction',
  limit: 50,
});

if (res.success && res.data) {
  for (const log of res.data) {
    console.log(`[${log.timestamp}] ${log.level.toUpperCase()} [${log.category}] ${log.message}`);
  }
}

Manage Rate Limits​

// Check rate limits for a project
const limitsRes = await engine.adminGetRateLimits('proj_abc123');

if (limitsRes.success && limitsRes.data) {
  for (const rl of limitsRes.data) {
    console.log(`${rl.endpoint}: ${rl.currentCount}/${rl.limit} (resets in ${rl.resetsIn}s)`);
    if (rl.isLimited) {
      console.log('  ** Currently rate-limited **');
    }
  }
}

// Clear rate limits for a project
const clearRes = await engine.adminClearRateLimits('proj_abc123');
if (clearRes.success && clearRes.data?.cleared) {
  console.log('Rate limits cleared');
}

Regenerate API Keys​

const res = await engine.adminRegenerateApiKey('proj_abc123');

if (res.success && res.data) {
  console.log('New client ID:', res.data.clientId);
  console.log('New secret key:', res.data.secretKey);
  // Communicate new keys to the project owner securely
}

List and Update Projects​

// List projects on the free plan
const res = await engine.adminListProjects({
  plan: 'free',
  sortBy: 'apiCalls',
  sortOrder: 'desc',
  pageSize: 10,
});

if (res.success && res.data) {
  for (const proj of res.data.items) {
    console.log(`${proj.name} | ${proj.plan} | Calls: ${proj.apiCallsThisPeriod}/${proj.apiCallLimit}`);
  }
}

// Upgrade a project
await engine.adminUpdateProject('proj_abc123', {
  plan: 'pro',
  apiCallLimit: 100000,
});

Next Steps​