Admin Endpoints

Platform administration — stats, user management, and session oversight. Requires admin role.

Platform Stats

GET /api/v1/admin/stats

Headers

• Authorization: Bearer <adminToken>
• X-Bulwark-Tenant: <tenant-id>

Response 200

{
  "data": {
    "users": {
      "total": 1240,
      "active30d": 892,
      "newThisMonth": 143
    },
    "agents": {
      "total": 78,
      "active": 64,
      "revoked": 14
    },
    "sessions": {
      "active": 203,
      "completedToday": 1842
    },
    "apiCalls": {
      "today": 48920,
      "thisMonth": 1203840
    }
  }
}

List Users

GET /api/v1/admin/users

Query Parameters

• limit — Results per page (default: 20)
• cursor — Pagination cursor
• search — Search by email or name
• role — Filter by role (user, admin)

Response 200

{
  "data": [
    {
      "id": "usr_01j...",
      "email": "user@example.com",
      "name": "Jane Doe",
      "role": "user",
      "status": "active",
      "createdAt": "2026-01-15T00:00:00Z",
      "lastLoginAt": "2026-03-17T22:00:00Z"
    }
  ],
  "pagination": { "cursor": "...", "hasMore": true }
}

Get User

GET /api/v1/admin/users/{userId}

Response 200

{
  "data": {
    "id": "usr_01j...",
    "email": "user@example.com",
    "name": "Jane Doe",
    "role": "user",
    "status": "active",
    "agents": ["agent_01j..."],
    "createdAt": "2026-01-15T00:00:00Z"
  }
}

Update User Role

PATCH /api/v1/admin/users/{userId}

Body

{
  "role": "admin"
}

Response 200

{
  "data": {
    "id": "usr_01j...",
    "role": "admin",
    "updatedAt": "2026-03-18T00:00:00Z"
  }
}

Suspend User

POST /api/v1/admin/users/{userId}/suspend

Suspends the user account and invalidates all tokens.

Response 200

{
  "data": {
    "id": "usr_01j...",
    "status": "suspended",
    "suspendedAt": "2026-03-18T00:00:00Z"
  }
}

List All Sessions

GET /api/v1/admin/sessions

Query Parameters

• agentId — Filter by agent
• userId — Filter by user
• status — active, completed, expired

Response 200

{
  "data": [
    {
      "sessionId": "sess_01j...",
      "agentId": "agent_01j...",
      "userId": "usr_01j...",
      "status": "active",
      "createdAt": "2026-03-18T13:00:00Z"
    }
  ],
  "pagination": { "cursor": "...", "hasMore": false }
}