Admin API endpoints

Admin endpoints are split across two service routes: /api/admin routes to the user service for user management, and /api/admin/tasks routes to the task service for task administration. All six endpoints require a JWT issued to an account with the admin role. Requests made with a standard user token — even a verified one — return 403 Forbidden.

A 403 response on any admin endpoint means the token in your Authorization header does not belong to an admin account. Log in with an admin-role account to obtain the correct token.

List all users

GET /api/admin/users Returns all registered user accounts.

Headers

Authorization

string

required

Bearer <token> — JWT from an admin account.

Example

curl --request GET \
  --url http://localhost:5000/api/admin/users \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "success": true,
  "message": "Users retrieved successfully",
  "data": [
    {
      "_id": "664a1f2e8b1c2d3e4f5a6b7c",
      "email": "user@example.com",
      "name": "Example User",
      "role": "user",
      "isVerified": false,
      "createdAt": "2025-05-01T10:00:00.000Z"
    }
  ]
}

Verify a user

PATCH /api/admin/users/:id/verify Marks a user account as verified, allowing the user to access task endpoints.

Headers

Authorization

string

required

Bearer <token> — JWT from an admin account.

Path parameters

string

required

The user’s unique identifier.

Example

curl --request PATCH \
  --url http://localhost:5000/api/admin/users/664a1f2e8b1c2d3e4f5a6b7c/verify \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "success": true,
  "message": "User verified successfully",
  "data": {
    "_id": "664a1f2e8b1c2d3e4f5a6b7c",
    "email": "user@example.com",
    "isVerified": true
  }
}

Delete a user

DELETE /api/admin/users/:id Permanently removes a user account and all associated data.

Headers

Authorization

string

required

Bearer <token> — JWT from an admin account.

Path parameters

string

required

The user’s unique identifier.

Example

curl --request DELETE \
  --url http://localhost:5000/api/admin/users/664a1f2e8b1c2d3e4f5a6b7c \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "success": true,
  "message": "User deleted successfully"
}

Assign a task

POST /api/admin/tasks/assign Creates a task and assigns it to a specific user. The assigned user can view the task in their task list once it is verified.

Headers

Authorization

string

required

Bearer <token> — JWT from an admin account.

Body parameters

userId

string

required

The ID of the user to assign the task to.

title

string

required

Task title.

description

string

Optional task description.

status

string

default:"pending"

Initial task status. One of pending, in-progress, or completed.

priority

string

default:"medium"

Task priority. One of low, medium, or high.

dueDate

string

Due date as an ISO 8601 string (e.g., 2025-12-31T00:00:00.000Z).

Example

curl --request POST \
  --url http://localhost:5000/api/admin/tasks/assign \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "664a1f2e8b1c2d3e4f5a6b7c",
    "title": "Review onboarding docs",
    "priority": "medium",
    "dueDate": "2025-11-01T00:00:00.000Z"
  }'

{
  "success": true,
  "message": "Task assigned successfully",
  "data": {
    "_id": "664b2a3f9c2d3e4f5a6b7d8e",
    "title": "Review onboarding docs",
    "userId": "664a1f2e8b1c2d3e4f5a6b7c",
    "status": "pending",
    "priority": "medium",
    "dueDate": "2025-11-01T00:00:00.000Z",
    "isVerifiedByAdmin": true,
    "createdAt": "2025-05-20T08:00:00.000Z"
  }
}

List pending tasks

GET /api/admin/tasks/pending Returns all tasks across all users that are awaiting admin verification.

Headers

Authorization

string

required

Bearer <token> — JWT from an admin account.

Example

curl --request GET \
  --url http://localhost:5000/api/admin/tasks/pending \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "success": true,
  "message": "Pending tasks retrieved successfully",
  "data": [
    {
      "_id": "664b2a3f9c2d3e4f5a6b7d8e",
      "title": "Review onboarding docs",
      "status": "pending",
      "priority": "medium",
      "isVerifiedByAdmin": false,
      "userId": "664a1f2e8b1c2d3e4f5a6b7c"
    }
  ]
}

Verify a task

PATCH /api/admin/tasks/:id/verify Marks a task as verified by an admin. Verified tasks are visible and usable by the assigned user.

Headers

Authorization

string

required

Bearer <token> — JWT from an admin account.

Path parameters

string

required

The task’s unique identifier.

Example

curl --request PATCH \
  --url http://localhost:5000/api/admin/tasks/664b2a3f9c2d3e4f5a6b7d8e/verify \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "success": true,
  "message": "Task verified successfully",
  "data": {
    "_id": "664b2a3f9c2d3e4f5a6b7d8e",
    "title": "Review onboarding docs",
    "isVerifiedByAdmin": true
  }
}

Overview

Endpoints

Admin API endpoints

List all users

Headers

Example

Verify a user

Headers

Path parameters

Example

Delete a user

Headers

Path parameters

Example

Assign a task

Headers

Body parameters

Example

List pending tasks

Headers

Example

Verify a task

Headers

Path parameters

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​List all users

​Headers

​Example

​Verify a user

​Headers

​Path parameters

​Example

​Delete a user

​Headers

​Path parameters

​Example

​Assign a task

​Headers

​Body parameters

​Example

​List pending tasks

​Headers

​Example

​Verify a task

​Headers

​Path parameters

​Example

Build docs developers (and LLMs) love

List all users

Headers

Example

Verify a user

Headers

Path parameters

Example

Delete a user

Headers

Path parameters

Example

Assign a task

Headers

Body parameters

Example

List pending tasks

Headers

Example

Verify a task

Headers

Path parameters

Example