​
Overview

The Admin API provides administrative functions for license management, user administration, and organization configuration. All endpoints require admin or owner role access.

​
Authentication

All admin endpoints require:
  • Valid Bearer token authentication
  • User must have admin or owner role in the organization
  • Automatic organization scoping

​
Endpoints

​
License Management

GET /api/admin/license Get license usage statistics and tier information. Response: 
{
  "data": {
    "tier": "growth",
    "maxUsers": 500,
    "activeUsers": 387,
    "usagePercentage": 77.4,
    "inactiveUsers": 23,
    "monthlyCost": 1935.00,
    "nextBillingDate": "2024-02-01T00:00:00Z"
  }
}
License Tiers:
  • Starter: €15/user/month, max 50 users
  • Growth: €10/user/month, 50-500 users
  • Enterprise: €7/user/month, 500+ users
Usage Alerts:
  • Green: <80% usage (healthy)
  • Yellow: 80-89% usage (monitor)
  • Orange: 90-99% usage (upgrade soon)
  • Red: 100%+ usage (immediate upgrade required)

​
User Management

GET /api/admin/users List all organization users with roles and activity status. Response: 
{
  "data": [
    {
      "id": "user-uuid-1",
      "email": "john.doe@company.com",
      "name": "John Doe",
      "role": "owner",
      "joinedAt": "2023-06-15T10:30:00Z",
      "lastActive": "2024-01-15T14:20:00Z",
      "status": "active"
    },
    {
      "id": "user-uuid-2",
      "email": "jane.smith@company.com",
      "name": "Jane Smith",
      "role": "admin",
      "joinedAt": "2023-08-01T09:15:00Z",
      "lastActive": "2024-01-10T16:45:00Z",
      "status": "inactive"
    }
  ]
}
User Roles:
  • Owner: Full access (billing, settings, all features)
  • Admin: Administrative access (users, analytics, settings - no billing)
  • Member: Standard access (create evidence, view own data)
Activity Status:
  • Active: Logged in within last 24 hours
  • Inactive: No activity for 30+ days
  • Suspended: Account temporarily disabled

​
Organization Settings

GET /api/admin/settings Retrieve current organization settings. Response: 
{
  "data": {
    "id": "org-uuid",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "industry": "technology",
    "size": "201-1000",
    "country": "United States",
    "timezone": "America/New_York",
    "logoUrl": "https://storage.example.com/logo.png",
    "brandColor": "#0d1594"
  }
}
PATCH /api/admin/settings Update organization settings. Request Body: 
{
  "name": "Acme Corporation Inc.",
  "industry": "technology",
  "size": "201-1000",
  "country": "United States",
  "timezone": "America/New_York",
  "brandColor": "#0d1594"
}

​
Configuration Options

​
Industry Categories

  • technology, healthcare, finance, education
  • retail, manufacturing, other

​
Organization Size

  • 1-10, 11-50, 51-200, 201-1000, 1000+

​
Branding (Enterprise Tier)

  • Custom brand colors (hex codes)
  • Logo URL (secure HTTPS)
  • White-label domain configuration

​
Business Rules

​
Access Control

  • Role Verification: Automatic role checking on all admin endpoints
  • Organization Scoping: All operations scoped to user’s organization
  • Audit Logging: All admin actions logged for compliance

​
License Enforcement

  • Real-time Tracking: Active user counts updated in real-time
  • Grace Period: 5% buffer above tier limits
  • Automatic Alerts: Email notifications at usage thresholds
  • Hard Limits: API calls blocked when limits exceeded

​
User Management

  • Inactive Detection: 30-day inactivity threshold
  • Bulk Operations: Support for bulk user role updates
  • Security: Secure password reset flows
  • Compliance: GDPR-compliant user data handling

​
Error Responses

Access Denied: 
{
  "error": "Admin access required",
  "details": {
    "requiredRole": "admin",
    "userRole": "member"
  }
}
License Exceeded: 
{
  "error": "License limit exceeded",
  "details": {
    "currentUsers": 520,
    "maxUsers": 500,
    "tier": "growth"
  }
}

​
Integration Examples

​
License Monitoring Dashboard

// Check license status
const license = await fetch('/api/admin/license')
  .then(r => r.json());

// Alert if approaching limit
if (license.usagePercentage > 80) {
  showUpgradeAlert(license);
}

​
User Activity Report

// Get user list with activity
const users = await fetch('/api/admin/users')
  .then(r => r.json());

// Filter inactive users
const inactiveUsers = users.data.filter(
  user => user.status === 'inactive'
);

​
Settings Update

// Update organization branding
await fetch('/api/admin/settings', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    brandColor: '#ff66c4',
    logoUrl: 'https://cdn.company.com/new-logo.png'
  })
});