144 lines
5.7 KiB
Markdown
144 lines
5.7 KiB
Markdown
---
|
|
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]]
|