Admin API

Full REST reference for the admin domain: user approvals/management, platform-wide workspace oversight, and aggregate metrics. All routes are under /api/admin, require a Cognito JWT (Authorization: Bearer <token>), and are backed by services/backend/lambda/admin_handler.py / admin_service.py. See specs/api/admin.md in the repo for the underlying spec this page is based on, and the Admin feature guide for the product-level behavior.

Endpoints at a glance

List users

GET /api/admin/users
GET /api/admin/users?status=pending
GET /api/admin/users?status=approved

// 200 Response
{
  "users": [
    {
      "user_id": "user_123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "role": "member",
      "status": "pending",
      "created_at": "2026-07-10T09:00:00+00:00",
      "last_login": null
    }
  ]
}

?status= accepts pending or approved; anything else (including rejected, a typo, or omitting it) returns every user rather than erroring.

status is derived, not stored as-is:

There is no "disabled" value this endpoint can ever return — see Set user status for why.

Approve user

POST /api/admin/users/{id}/approve

// 200 Response
{ "status": "approved", "user_id": "user_123" }

Three side effects happen in sequence, and all three must succeed for the call to succeed:

1. DynamoDB: approved → true.
2. Cognito: AdminUpdateUserAttributes(custom:approved=true) + AdminEnableUser.
3. Slack: DM the user "Account Approved... You can now log in" (looks up their Slack user ID by email first).

Reject user

POST /api/admin/users/{id}/reject

// 200 Response
{ "status": "rejected", "user_id": "user_123" }

Sets approved → false, status → "rejected" in DynamoDB, and calls Cognito AdminDisableUser.

Set user role

PUT /api/admin/users/{id}/role

// Request
{ "role": "admin" }

role must be admin or member. Updates both the DynamoDB role attribute and the Cognito custom:role attribute in one call.

// 200 Response
{ "status": "updated", "user_id": "user_123", "role": "admin" }

Set user status

PUT /api/admin/users/{id}/status

// Request
{ "enabled": false }

enabled is required (missing/null → 400). Calls Cognito AdminEnableUser or AdminDisableUser accordingly.

// 200 Response
{ "status": "updated", "user_id": "user_123", "enabled": false }

List workspaces

GET /api/admin/workspaces

// 200 Response
{
  "workspaces": [
    {
      "workspace_id": "ws_123",
      "name": "Acme Marketing",
      "description": "",
      "owner_id": "user_123",
      "status": "active",
      "created_at": "2026-06-01T09:00:00+00:00",
      "updated_at": "2026-06-01T09:00:00+00:00",
      "owner_name": "Jane Doe",
      "owner_email": "jane@example.com"
    }
  ]
}

Includes soft-deleted workspaces (no status filter on the scan). A soft-deleted workspace additionally has a deleted_at field. If the owner's user record is missing, owner_name/owner_email come back as "" rather than the row erroring out.

Recover workspace

POST /api/admin/workspaces/{workspace_id}/recover

// 200 Response
{ "workspace_id": "ws_123", "status": "active" }

Requires the workspace to currently be status: "deleted". Flips it back to active and removes deleted_at. Does not restore or touch any members/posts/ideas — those were never removed by the delete in the first place.

Delete workspace

DELETE /api/admin/workspaces/{workspace_id}

// 200 Response
{ "workspace_id": "ws_123", "status": "deleted" }

Soft-deletes an active workspace (status → "deleted", deleted_at stamped). Returns 200 with a body, not 204.

Metrics

GET /api/admin/metrics

// 200 Response
{
  "total_users": 42,
  "pending_users": 3,
  "total_workspaces": 8,
  "total_posts": 0,
  "total_ideas": 0,
  "posts_published_last_30_days": 17,
  "active_users_last_7_days": 0
}