System Administrator Guide¶

Role Overview¶

As a System Administrator, you are responsible for:

• Managing tenants and organizational boundaries
• Administering users and their role assignments
• Generating and rotating API keys for integrations
• Monitoring system health and performance metrics

CalcBridge provides comprehensive administrative tools with full audit trails for all administrative actions.

Daily Workflow¶

flowchart LR
    A[Monitor Health] --> B[Manage Users]
    B --> C[Review API Usage]
    C --> D[Handle Support]
    D --> E[Review Audit Logs]

    style A fill:#DCFCE7,stroke:#22C55E
    style B fill:#DBEAFE,stroke:#3B82F6
    style C fill:#FEF3C7,stroke:#F59E0B
    style D fill:#FEE2E2,stroke:#EF4444
    style E fill:#EDE9FE,stroke:#8B5CF6

Step 1: Monitor Health¶

Start your day by checking system health dashboards:

# Health check
curl https://api.calcbridge.io/health/ready

# Response
{
  "status": "healthy",
  "checks": {
    "database": "healthy",
    "cache": "healthy",
    "workers": "healthy"
  },
  "version": "1.0.0"
}

Step 2: Manage Users¶

Handle user provisioning and access requests:

• Create new user accounts
• Modify role assignments
• Deactivate departing users
• Reset credentials

Step 3: Review API Usage¶

Monitor API key usage and rate limiting:

API Usage Summary (Last 24h)
============================
Total Requests: 45,892
Unique API Keys: 12
Rate Limit Hits: 3
Failed Auth: 7

Step 4: Handle Support¶

Address user issues and requests:

• Access problems
• Performance questions
• Feature requests
• Bug reports

Step 5: Review Audit Logs¶

Review administrative actions for compliance:

# Get admin audit logs
curl "https://api.calcbridge.io/api/v1/audit/logs?event_type=admin.*" \
  -H "Authorization: Bearer $TOKEN"

Key Features¶

Tenant Management¶

Multi-tenant architecture with complete data isolation:

User Role Management¶

Built-in roles with granular permissions:

API Key Management¶

Secure API key lifecycle:

• Generate keys with custom scopes
• Set expiration dates
• Monitor usage
• Rotate keys without downtime

System Monitoring¶

Built-in observability:

• Prometheus metrics endpoint
• Health check endpoints
• Request tracing with OpenTelemetry
• Grafana dashboard templates

Step-by-Step Tutorials¶

Creating New Tenants¶

Provision new organizational tenants in CalcBridge.

Tenant Structure¶

flowchart TB
    subgraph Platform["CalcBridge Platform"]
        subgraph T1["Tenant: Acme Corp"]
            U1[Users]
            W1[Workbooks]
            D1[Data]
        end
        subgraph T2["Tenant: Beta Inc"]
            U2[Users]
            W2[Workbooks]
            D2[Data]
        end
    end

    style T1 fill:#DBEAFE,stroke:#3B82F6
    style T2 fill:#DCFCE7,stroke:#22C55E

Tutorial¶

1. Navigate to Tenant Management

Go to Admin > Tenants > Create New Tenant

2. Configure Tenant Details

{
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "subscription_tier": "standard",
  "settings": {
    "max_users": 25,
    "max_workbooks": 100,
    "max_storage_gb": 50,
    "features": {
      "what_if_scenarios": true,
      "compliance_testing": true,
      "api_access": true,
      "sso_enabled": false
    }
  },
  "billing": {
    "contact_email": "billing@acme.com",
    "billing_cycle": "monthly"
  }
}

3. Create Initial Admin User

{
  "email": "admin@acme.com",
  "full_name": "John Smith",
  "role": "owner",
  "send_invitation": true
}

4. Configure Tenant Settings

{
  "security": {
    "password_policy": {
      "min_length": 12,
      "require_uppercase": true,
      "require_number": true,
      "require_special": true
    },
    "mfa_required": false,
    "session_timeout_minutes": 60,
    "allowed_ip_ranges": []
  }
}

{
  "rate_limits": {
    "requests_per_minute": 100,
    "requests_per_hour": 3000,
    "uploads_per_day": 50,
    "calculations_per_hour": 500
  }
}

{
  "features": {
    "what_if_scenarios": true,
    "compliance_testing": true,
    "api_access": true,
    "webhooks": true,
    "custom_functions": false,
    "white_label": false
  }
}

5. Activate Tenant

curl -X POST "https://api.calcbridge.io/api/v1/admin/tenants/{tenant_id}/activate" \
  -H "Authorization: Bearer $TOKEN"

Managing User Roles¶

Configure user access and permissions.

Role Hierarchy¶

flowchart TB
    Owner --> Admin
    Admin --> Analyst
    Analyst --> Viewer

    style Owner fill:#EF4444,stroke:#DC2626,color:#fff
    style Admin fill:#F59E0B,stroke:#D97706
    style Analyst fill:#3B82F6,stroke:#2563EB,color:#fff
    style Viewer fill:#6B7280,stroke:#4B5563

Permission Matrix¶

Creating Users¶

Via Web Interface:

1. Navigate to Admin > Users > Add User
2. Enter user details
3. Select role
4. Choose to send invitation or set password

Via API:

curl -X POST "https://api.calcbridge.io/api/v1/admin/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "analyst@acme.com",
    "full_name": "Jane Analyst",
    "role": "analyst",
    "send_invitation": true
  }'

Modifying User Roles¶

# Change user role
curl -X PATCH "https://api.calcbridge.io/api/v1/admin/users/{user_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "role": "admin"
  }'

Deactivating Users¶

# Deactivate user (soft delete)
curl -X POST "https://api.calcbridge.io/api/v1/admin/users/{user_id}/deactivate" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "reason": "Employee departure",
    "revoke_sessions": true
  }'

Generating API Keys¶

Create and manage API keys for programmatic access.

API Key Types¶

Creating an API Key¶

1. Navigate to API Keys

Go to Admin > API Keys > Generate New Key

2. Configure Key Properties

{
  "name": "Production Integration",
  "description": "Backend service for automated uploads",
  "type": "service",
  "scopes": [
    "workbooks:read",
    "workbooks:write",
    "calculations:execute",
    "compliance:run"
  ],
  "expiration": "2025-01-15",
  "rate_limit": {
    "requests_per_minute": 500
  },
  "allowed_ips": [
    "10.0.0.0/8",
    "192.168.1.100"
  ]
}

3. Generate and Store Key

API Key Generated
=================
Key ID: key_abc123
Key: cb_sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789

This key will not be shown again. Store it securely.

4. Test the Key

curl -X GET "https://api.calcbridge.io/api/v1/workbooks" \
  -H "X-API-Key: cb_sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789"

Rotating API Keys¶

# Create new key (same permissions)
curl -X POST "https://api.calcbridge.io/api/v1/admin/api-keys/{key_id}/rotate" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "grace_period_hours": 24
  }'

During the grace period, both old and new keys work, allowing zero-downtime rotation.

Reading Prometheus Metrics¶

Monitor system performance using Prometheus metrics.

Accessing Metrics¶

# Get raw Prometheus metrics
curl "https://api.calcbridge.io/metrics"

Key Metrics¶

Request Metrics:

# Total HTTP requests
http_requests_total{method="POST", endpoint="/api/v1/calculations/evaluate", status="200"} 45892

# Request latency histogram
http_request_duration_seconds_bucket{endpoint="/api/v1/workbooks",le="0.1"} 42000
http_request_duration_seconds_bucket{endpoint="/api/v1/workbooks",le="0.5"} 44500
http_request_duration_seconds_bucket{endpoint="/api/v1/workbooks",le="1.0"} 45800

# P95 latency
http_request_duration_seconds{quantile="0.95"} 0.187

Business Metrics:

# Active tenants
calcbridge_active_tenants 47

# Workbooks uploaded today
calcbridge_workbooks_uploaded_total{period="today"} 234

# Compliance tests run
calcbridge_compliance_tests_total{result="pass"} 1892
calcbridge_compliance_tests_total{result="fail"} 43

# Calculations executed
calcbridge_calculations_total 89234

Infrastructure Metrics:

# Database connection pool
db_connection_pool_size 20
db_connection_pool_used 8

# Cache hit rate
cache_hits_total 145000
cache_misses_total 2340

# Celery worker status
celery_workers_active 4
celery_tasks_pending 12

Grafana Dashboard¶

Import the CalcBridge Grafana dashboard:

Dashboard Panels:
  - Request Rate (req/sec)
  - Error Rate (%)
  - P95 Latency (ms)
  - Active Users
  - Database Connections
  - Cache Hit Rate
  - Celery Queue Depth
  - Compliance Test Results

Alert Rules¶

Configure Prometheus alerts:

groups:
  - name: calcbridge
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.01
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "High error rate detected"

      - alert: HighLatency
        expr: histogram_quantile(0.95, http_request_duration_seconds_bucket) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "API latency above 500ms"

      - alert: DatabaseConnectionsHigh
        expr: db_connection_pool_used / db_connection_pool_size > 0.8
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Database connection pool >80% utilized"

Tips and Best Practices¶

Security Best Practices¶

User Management¶

1. Principle of least privilege: Grant minimum necessary permissions
2. Regular access reviews: Audit user access quarterly
3. Prompt deactivation: Remove access immediately on departure
4. Document exceptions: Log any special access grants

Monitoring Strategy¶

Incident Response¶

flowchart TB
    A[Alert Triggered] --> B{Severity?}
    B -->|Critical| C[Page On-Call]
    B -->|Warning| D[Create Ticket]
    C --> E[Investigate]
    D --> E
    E --> F[Mitigate]
    F --> G[Document]
    G --> H[Post-Mortem]

    style C fill:#EF4444,stroke:#DC2626,color:#fff
    style D fill:#F59E0B,stroke:#D97706

Quick Reference¶

Health Check Endpoints¶

Admin API Endpoints¶

# Tenant management
GET /api/v1/admin/tenants
POST /api/v1/admin/tenants
GET /api/v1/admin/tenants/{id}
PATCH /api/v1/admin/tenants/{id}

# User management
GET /api/v1/admin/users
POST /api/v1/admin/users
PATCH /api/v1/admin/users/{id}
POST /api/v1/admin/users/{id}/deactivate

# API key management
GET /api/v1/admin/api-keys
POST /api/v1/admin/api-keys
DELETE /api/v1/admin/api-keys/{id}
POST /api/v1/admin/api-keys/{id}/rotate

# System metrics
GET /metrics
GET /api/v1/admin/metrics/summary

Subscription Tiers¶

Next Steps¶

• Complete this guide
• Review system health dashboard
• Create a new tenant
• Generate an API key
• Set up monitoring alerts

View Architecture API Reference