---
type: api
title: Admin Endpoints
description: User management endpoints mounted under /api/v1/admin (admin role required).
tags: [api, admin, users]
timestamp: 2026-07-21T18:28:00Z
---

# Endpoints

| Method  | Path                  | Auth    | Source                                              |
|---------|-----------------------|---------|-----------------------------------------------------|
| `GET`   | `/api/v1/admin/users` | Admin   | `backend/src/modules/admin/admin.controller.ts`     |
| `POST`  | `/api/v1/admin/users` | Admin   | Same.                                               |
| `PATCH` | `/api/v1/admin/users/:id` | Admin | Same.                                            |
| `DELETE`| `/api/v1/admin/users/:id` | Admin | Same.                                            |

# Guard chain

1. `JwtAuthGuard` (global) validates the access token unless the handler
   is `@Public()`. Admin handlers are not.
2. `AdminGuard` (`backend/src/common/guards/admin.guard.ts`) requires
   `req.user.role === 'admin'`.

# Behavior

* `AdminService` enforces the **last-admin invariant** (`LAST_ADMIN` /
   `409`) — the final admin row cannot be demoted or deleted.
* `POST /api/v1/admin/users` creates a new user; `PATCH /api/v1/admin/users/:id`
   changes role / status; `DELETE /api/v1/admin/users/:id` removes the row.

# See also

- [Backend Module Map](/architecture/backend-modules.md)
- [Admin Shell & User Management](/guides/admin-shell.md)
- [REST API Overview](/api/rest-overview.md)