---
title: Admin API
tags: [api, admin, reference]
---

# Admin API

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` | Delete user (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 |

## 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/shkeeper/:id/release` | Build escrow-release tx |
| `POST /api/payment/shkeeper/:id/release/confirm` | Confirm release tx hash |
| `POST /api/payment/shkeeper/:id/refund` | Build refund tx |
| `POST /api/payment/shkeeper/: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 |

## 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`](../../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:**
```ts
{
  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.

## Analytics

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

- `GET /api/users/admin/stats` (user metrics)
- `GET /api/payment/stats` (payment aggregates)
- `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]]