Users API

User management, roles, and session control endpoints

Users API

The Users API provides administrative endpoints for managing user accounts, roles, bans, and sessions. All endpoints require admin authentication.

Authentication

All endpoints require:

• Valid session with admin role
• Admin guard (isAdminUser check)

Authorization: Bearer <session-token>

List users

cURL

curl -X GET https://your-domain.com/api/admin/users \
  -H "Authorization: Bearer <session-token>"

Query Parameters:

page · number

Page number for pagination

limit · number

Number of users per page

search · string

Search query for filtering users

role · string

Filter by role (e.g., “admin”, “moderator”)

Response:

users · array

Array of user objects

Show User object

id · string

User ID

name · string

User name

email · string

User email

emailVerified · boolean

Email verification status

image · string

User avatar URL

createdAt · string

Account creation timestamp

updatedAt · string

Last update timestamp

banned · boolean

Ban status

banReason · string

Reason for ban (if banned)

total · number

Total number of users

page · number

Current page number

limit · number

Users per page

User management actions

All user management operations use the same endpoint with different action parameters.

Endpoint: POST /api/admin/users

Set user role

Assign a role to a user.

cURL

curl -X POST https://your-domain.com/api/admin/users \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set-role",
    "userId": "user-id",
    "role": "moderator"
  }'

Request Body:

action · string · required

Must be "set-role"

userId · string · required

Target user ID

role · string · required

Role to assign: "admin", "moderator", "author", "owner", "citizen"

Ban user

Ban a user account.

cURL

curl -X POST https://your-domain.com/api/admin/users \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "ban",
    "userId": "user-id",
    "reason": "Violation of terms of service"
  }'

Request Body:

action · string · required

Must be "ban"

userId · string · required

User ID to ban

reason · string

Reason for ban (optional but recommended)

Unban user

Remove ban from a user account.

{
  "action": "unban",
  "userId": "user-id"
}

List user sessions

Get all active sessions for a specific user.

{
  "action": "list-sessions",
  "userId": "user-id"
}

Response:

[
  {
    "id": "session-id",
    "userId": "user-id",
    "token": "session-token",
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "expiresAt": "2024-12-31T23:59:59Z",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Revoke user sessions

Revoke all active sessions for a user (force logout).

{
  "action": "revoke-sessions",
  "userId": "user-id"
}

Response codes

200 · success

Operation successful

400 · error

Invalid request (missing action, userId, or role)

403 · error

Forbidden - requires admin role

404 · error

User not found

500 · error

Internal server error

Error responses

{
  "error": "missing_action"
}

{
  "error": "missing_userId"
}

{
  "error": "missing_role"
}

{
  "error": "unknown_action"
}

{
  "error": "forbidden"
}

Implementation reference

Source: /src/pages/api/admin/users.ts

The implementation uses the following admin utilities:

• listUsers() - From @lib/admin/users
• setUserRole() - Role assignment with validation
• banUser() - Ban with optional reason
• unbanUser() - Remove ban
• listUserSessions() - Session enumeration
• revokeUserSessions() - Force logout

Security Note: All actions are logged in the audit log. Banning users revokes their active sessions automatically through the authentication system.

See also

• User Roles & Permissions
• Authentication System
• Audit Logging