st body. All necessary context is derived from the authenticated session attached to the request.

Headers

Header	Required	Description
Cookie	Yes	Contains the platform session token. The auth() utility parses this to validate identity and role.
Accept	Optional	Defaults to application/json.

Request Body

None

Example Request

GET /api/admin/users HTTP/1.1
Host: api.codcompass.com
Cookie: session=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

---

4. Response Format

Success Response (200 OK)

Returns a JSON object containing a users array. Each user object includes only the fields explicitly selected in the Prisma query. Sensitive fields like passwords, tokens, or internal metadata are intentionally excluded.

Field	Type	Description
id	string	Unique user identifier
email	string	Primary email address
name	string | null	Display name (nullable)
role	string	Account role (e.g., USER, ADMIN)
planType	string | null	Subscription tier or plan identifier
subscriptionStatus	string | null	Current billing state (e.g., active, past_due, canceled)
isBanned	boolean	Account restriction flag
createdAt	string	ISO 8601 timestamp of account creation

Example JSON

{
  "users": [
    {
      "id": "usr_9f8e7d6c5b4a",
      "email": "admin@example.com",
      "name": "Platform Admin",
      "role": "ADMIN",
      "planType": "enterprise",
      "subscriptionStatus": "active",
      "isBanned": false,
      "createdAt": "2023-11-15T08:30:00.000Z"
    },
    {
      "id": "usr_1a2b3c4d5e6f",
      "email": "user@example.com",
      "name": null,
      "role": "USER",
      "planType": "free",
      "subscriptionStatus": null,
      "isBanned": false,
      "createdAt": "2024-02-10T14:22:11.000Z"
    }
  ]
}

Error Responses

Status Code	Response Body	Trigger Condition
403 Forbidden	{ "error": "Forbidden" }	Missing session, invalid token, or user role is not ADMIN
500 Internal Server Error	{ "error": "Internal server error" }	Database connection failure, Prisma query error, or unhandled runtime exception

---

5. Usage Example

cURL

curl -X GET "https://api.codcompass.com/api/admin/users" \
  -H "Cookie: session=your_admin_session_token_here" \
  -H "Accept: application/json"

JavaScript (Fetch API)

const response = await fetch('/api/admin/users', {
  method: 'GET',
  credentials: 'include', // Ensures cookies are sent
  headers: { 'Accept': 'application/json' }
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}

const data = await response.json();
console.log(data.users);

---

6. Common Pitfalls

1. Authentication Metadata Mismatch
   The endpoint metadata may list authentication as Public (No Auth), but the route handler explicitly validates the session and checks for role === 'ADMIN'. Developers testing without an admin session will consistently receive 403 Forbidden. Always verify role assignment in your test environment before debugging connectivity issues.

2. Unexpected Caching Behavior
   The route declares export const dynamic = 'force-dynamic', which instructs Next.js to bypass static generation and always execute the handler. However, reverse proxies, CDNs, or browser caches may still store responses if Cache-Control headers are not explicitly set. If you require real-time data, ensure your infrastructure respects no-cache directives or append cache-busting parameters.

3. Assuming Full User Payloads
   The Prisma query uses a strict select clause. Fields like updatedAt, password, emailVerified, or custom metadata are intentionally omitted for security and performance. If your integration expects additional fields, you must either extend the route handler or use a dedicated user detail endpoint. Do not assume the array structure; the response is always wrapped in a { users: [...] } object.

---

7. Related Endpoints

This endpoint is typically used as the foundation for administrative workflows. It pairs naturally with:

• GET /api/auth/session – Verify current user identity and role before calling admin routes.
• PATCH /api/admin/users/[id] – Update specific user attributes (role, ban status, plan) after retrieving the list.
• POST /api/admin/users/export – Trigger bulk data exports for compliance or analytics pipelines.

When building admin dashboards, use this endpoint to populate initial user tables, then leverage detail or mutation endpoints for granular account management. Always handle 403 responses gracefully in UI components to prevent unauthorized access attempts from surfacing as generic network errors.