Platform API

Server: Central Monolithic Server
URL Prefix: /api/v1/platform/*
Purpose: Analytics, subscriptions, and system administration for executive and operational oversight.

Overview

The Platform API provides internal operations, analytics aggregation, and business intelligence. It is primarily consumed by the Admin Dashboard and executive views.

Quick Endpoint Reference

User Management

Method Endpoint Purpose Docs
GET /api/v1/platform/admin/users List all users Admin API
GET /api/v1/platform/admin/users/{id} Get user details Admin API
GET /api/v1/platform/admin/users/{id}/audit-trail User activity log Admin API
POST /api/v1/platform/admin/users/{id}/suspend Suspend account Admin API
POST /api/v1/platform/admin/users/{id}/revoke-sessions Revoke all sessions Admin API
POST /api/v1/platform/admin/users/{id}/reset-password Send password reset Admin API
PATCH /api/v1/platform/admin/users/{id} Update user role Admin API
DELETE /api/v1/platform/admin/users/{id} Delete account (GDPR) Admin API

Tenant Management

Method Endpoint Purpose Docs
GET /api/v1/platform/admin/tenants List all tenants Admin API
GET /api/v1/platform/admin/tenants/{id} Get tenant details Admin API
PATCH /api/v1/platform/admin/tenants/{id} Plan overrides Admin API
POST /api/v1/platform/admin/tenants/test Create test tenant Admin API
GET /api/v1/platform/admin/tenants/{id}/feature-flags Get feature flags Admin API
PATCH /api/v1/platform/admin/tenants/{id}/feature-flags Update feature flags Admin API

Plan Management

Method Endpoint Purpose Docs
GET /api/v1/platform/admin/plans List all plans Plans API
GET /api/v1/platform/admin/plans/{id} Get plan details Plans API
POST /api/v1/platform/admin/plans Create plan Plans API
PUT /api/v1/platform/admin/plans/{id} Update plan Plans API

Finance

Method Endpoint Purpose Docs
GET /api/v1/platform/finance/subscription-summary Subscription counts Finance API
GET /api/v1/platform/finance/stripe-sync-status Webhook health Finance API
POST /api/v1/platform/finance/sync-transaction Force sync Finance API

System Monitoring

Method Endpoint Purpose Docs
GET /api/v1/platform/system/queues List queues System API
GET /api/v1/platform/system/queues/{name}/jobs List queue jobs System API
POST /api/v1/platform/system/queues/{name}/pause Pause queue System API
POST /api/v1/platform/system/queues/{name}/resume Resume queue System API
POST /api/v1/platform/system/jobs/{id}/retry Retry job System API
DELETE /api/v1/platform/system/jobs/{id} Delete job System API
GET /api/v1/platform/system/infrastructure/health Service health System API
GET /api/v1/platform/system/infrastructure/ip-reputation IP reputation System API
GET /api/v1/platform/system/infrastructure/alerts Infra alerts System API
GET /api/v1/platform/system/logs Search logs System API
GET /api/v1/platform/system/logs/export Export logs System API

Vault Secrets Management

Method Endpoint Purpose Docs
GET /api/v1/admin/vault/health Vault health Vault API
GET /api/v1/admin/vault/backup-status Backup status Vault API
POST /api/v1/admin/vault/backup Force backup Vault API
GET /api/v1/admin/secrets/tenants List tenant secrets Vault API
GET /api/v1/admin/secrets/tenant/{id} Tenant secret details Vault API
GET /api/v1/admin/secrets/tenant/{id}/smtp-credentials View SMTP credentials Vault API
POST /api/v1/admin/secrets/tenant/{id}/rotate Rotate secret Vault API
POST /api/v1/admin/secrets/rotate-all Bulk rotation Vault API
GET /api/v1/admin/vault/audit-logs Vault audit logs Vault API

Endpoint Categories (Detailed)

1. Subscriptions & Billing

Documentation: Subscriptions API

Manage tenant subscriptions, billing, and payment records.

Key Endpoints:

  • GET /api/v1/platform/subscriptions - List subscriptions
  • GET /api/v1/platform/tenants/{id}/subscription - Get tenant subscription
  • GET /api/v1/platform/subscriptions/analytics - Revenue metrics

2. System Analytics

Documentation: Analytics API

System-wide metrics, revenue protection, and cost optimization.

Key Endpoints:

  • GET /api/v1/platform/system/overview - System health
  • GET /api/v1/platform/system/revenue-protection - Business metrics
  • GET /api/v1/platform/system/cost-optimization - Cost analysis

3. Admin Operations

Documentation: Admin API

User management, tenant management, and feature flags.

4. Plan Management

Documentation: Plans API

Subscription plan configuration, limits, and Stripe mappings.

5. Finance

Documentation: Finance API

Subscription monitoring and Stripe webhook status.

6. System Monitoring

Documentation: System Monitoring API

Infrastructure health, queue monitoring, and log access.

7. Vault Management

Documentation: Vault API

HashiCorp Vault secrets management, rotation, and audit.

Authentication

All endpoints require a valid session authenticated via NileDB with appropriate RBAC roles.

Required Roles:

Role Access Level
super_admin Full access to all platform admin endpoints
admin Tenant and user management (view-only for some)
support Read-only access, no PII
finance Finance dashboard and Stripe sync endpoints
ops System monitoring and queue management
qa Sandbox-only access

Pagination Strategy

All list endpoints support offset-based pagination to enable “Jump to page X” navigation:

Parameter Description Default Max
limit Max results per page 50 100
offset Number of records to skip 0 —

Response Pagination Envelope:

{
  "pagination": {
    "total": 1234,
    "limit": 50,
    "offset": 0
  }
}

Common Patterns

Response Envelope 

{
  "success": true,
  "data": { ... },
  "meta": {
    "data_source": "backbone_api",
    "last_updated": "ISO8601"
  }
}

Error Response 

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "User does not have required permissions"
  }
}

Route Specifications

Feature Documentation