nick-doc/03 - API Reference/Admin API.md

title, tags

title	tags
Admin API	api admin reference

Admin API

Last updated: 2026-05-29 — aligned with code (see Doc vs Code Audit Report)

There is no single /api/admin namespace — admin-only endpoints are scattered across the service routers. This page catalogs them in one place. All require Bearer JWT with req.user.role === 'admin'. The two enforcement patterns are:

• Middleware: authorizeRoles('admin') after authenticateToken (used by the dispute, data-cleanup, blog routers).
• Inline check inside the handler: if (req.user.role !== 'admin') return 403 (used by user, points, payment routes).

User management

See full descriptions in User API.

Endpoint	Action
POST /api/user/admin/create	Create user with role/status
DELETE /api/user/admin/:userId	Soft delete user — sets status='deleted' (admins cannot delete each other)
PATCH /api/user/admin/:userId/status	Activate / suspend
PATCH /api/user/admin/:userId/toggle-status	Flip active flag
PATCH /api/user/admin/:userId/role	Change role
GET /api/user/admin/list	Paginated directory + stats
GET /api/user/admin/:userId/dependencies	Pre-delete dependency check
GET /api/users/admin/stats	Aggregate user analytics
GET /api/users/admin/:userId	Full user detail (admin view)
PUT /api/users/admin/:userId	Mass update user
PUT /api/users/admin/update/:email	Mass update by email
PATCH /api/users/admin/:userId/password	Force password reset (wipes refresh tokens)
POST /api/users/admin/:userId/resend-verification	Resend verification email

⚠️ KNOWN BUG — HTTP verb mismatch (status/role updates): The frontend Redux actions for updateUserStatus and updateUserRole send PUT requests, but the backend registers these handlers under PATCH. These calls will receive 404 Method Not Found responses until the frontend is corrected to use PATCH.

⚠️ KNOWN BUG — Status value mismatch: The frontend sends 'inactive' and 'pending' as status values when updating user status. The backend only accepts 'active', 'suspended', or 'deleted'. Sending 'inactive' or 'pending' will be rejected or silently ignored.

Hard vs. soft delete note: The legacy route DELETE /users/admin/:id performs a hard delete (findByIdAndDelete). The current route DELETE /api/user/admin/:userId performs a soft delete (sets status='deleted'). Always use the current /api/user/admin/:userId route to preserve data integrity.

Listing / marketplace moderation

See Marketplace API. Admins can use most marketplace endpoints with elevated privileges (e.g. delete any purchase request, override offer status). Specific admin-only actions:

Endpoint	Action
PUT /api/marketplace/offers/:id/status	Direct status mutation including admin overrides
POST /api/marketplace/purchase-requests/:id/release-payment	Force escrow release
PATCH /api/marketplace/purchase-requests/:id/status (any → any)	Override request state machine

Template approval is implicit: admins use the same template CRUD endpoints with override privileges.

Dispute mediation

See Dispute API.

Endpoint	Action
POST /api/disputes/:id/assign	Assign moderator
PATCH /api/disputes/:id/status	Update status
POST /api/disputes/:id/resolve	Final decision (buyer / seller / split)
GET /api/disputes/statistics	Admin dashboard data

Manual payment operations

See Payment API.

Endpoint	Action
POST /api/payment/payments/cleanup-pending	Delete stale pending payments
POST /api/payment/payments/:id/fetch-tx	Re-query chain for missing tx hash
POST /api/payment/payments/auto-fetch-missing	Batch tx-hash backfill
POST /api/payment/:id/release	Build escrow-release tx
POST /api/payment/:id/release/confirm	Confirm release tx hash
POST /api/payment/:id/refund	Build refund tx
POST /api/payment/:id/refund/confirm	Confirm refund tx hash
POST /api/payment/shkeeper/payout	Create payout task
GET /api/payment/shkeeper/webhook-stats	Webhook telemetry
POST /api/payment/decentralized/admin-payout	Direct admin-wallet payout

⚠️ Path correction: Release/refund routes do not include a /shkeeper/ segment. The correct paths are /api/payment/:id/release, /api/payment/:id/release/confirm, etc. (Previously documented incorrectly as /api/payment/shkeeper/:id/….)

Points (admin)

See Points API.

Endpoint	Action
POST /api/points/admin/add	Manually grant / deduct points for a user

Data cleanup

Router: backend/src/services/admin/dataCleanupRoutes.ts. Mounted under /api/admin/cleanup/*. The router applies authenticateToken + authorizeRoles('admin') to every endpoint.

GET /api/admin/cleanup/stats

Description: Per-collection document counts and sizes. Response 200: { success, data: { collections: [{ name, count, sizeBytes }] } }

GET /api/admin/cleanup/collections

Description: List collections that can be cleaned and the supported flags. Response 200: { success, data: { collections, options } }

POST /api/admin/cleanup/clean

Description: Bulk delete records. Defaults to dryRun: true and keepAdmins: true. Request body:

{
  collections?: string[];        // default ["all"]
  dryRun?: boolean;              // default true
  keepAdmins?: boolean;          // default true
  olderThanDays?: number;        // optional age filter
  confirm?: "DELETE_ALL_DATA";   // required for actual deletion
}

Response 200: { success, data: { deletedCounts, dryRun } }

DELETE /api/admin/cleanup/user/:userId

Description: Cascade-delete all data for a specific user (GDPR). Requires ?confirm=DELETE_USER_DATA for real execution. Query params: dryRun=true|false, confirm=DELETE_USER_DATA

POST /api/admin/cleanup/temp

Description: Purge temporary data older than N hours (verification codes, file temp uploads). Request body: { olderThanHours?: number } (default 24)

POST /api/admin/cleanup/seed-templates

Description: Re-runs the request templates seeder (production safe; idempotent).

POST /api/admin/cleanup/seed-all

Description: Seeds users, addresses, and templates in dependency order. Used to bootstrap a fresh staging environment.

Scanner / monitoring

GET /api/admin/scanner/status

Description: Returns the current state of the blockchain scanner / wallet monitor. ⚠️ SECURITY BUG — NO AUTHENTICATION: Despite being mounted under /api/admin/ and documented as admin-only, this endpoint has no authenticateToken or authorizeRoles guard. Any unauthenticated request can read scanner state.

⚠️ NOT IMPLEMENTED: The following endpoints do not exist in the codebase:

• GET /api/admin/settings/confirmation-thresholds/history — only the current-values GET /api/admin/settings/confirmation-thresholds and per-chain PATCH /api/admin/settings/confirmation-thresholds/:chainId exist.
• POST /api/admin/rn/networks/reload — the network registry cannot be reloaded at runtime via HTTP.
• POST /api/admin/rn/networks/probe/:chainId — no per-chain probe endpoint exists.

Analytics

There is no dedicated analytics router. Admin dashboards stitch together:

• GET /api/users/admin/stats (user metrics)
• GET /api/payment/stats (payment aggregates — note: 'completed' status is excluded from successfulPayments count)
• GET /api/disputes/statistics (dispute KPIs)
• GET /api/admin/cleanup/stats (collection sizes)
• GET /api/payment/shkeeper/webhook-stats (provider health)
• GET /api/payment/shkeeper/wallet-monitor/status (chain monitor)

Related

• Admin Console Architecture
• Authorization Model
• Error Codes