> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Ishaq74/concordia/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

```typescript theme={null}
Authorization: Bearer <session-token>
```

## List users

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://your-domain.com/api/admin/users \
    -H "Authorization: Bearer <session-token>"
  ```

  ```typescript SDK theme={null}
  const response = await fetch('/api/admin/users', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${sessionToken}`
    }
  });
  const users = await response.json();
  ```
</CodeGroup>

**Query Parameters:**

<ParamField query="page" type="number">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="number">
  Number of users per page
</ParamField>

<ParamField query="search" type="string">
  Search query for filtering users
</ParamField>

<ParamField query="role" type="string">
  Filter by role (e.g., "admin", "moderator")
</ParamField>

**Response:**

<ResponseField name="users" type="array">
  Array of user objects

  <Expandable title="User object">
    <ResponseField name="id" type="string">
      User ID
    </ResponseField>

    <ResponseField name="name" type="string">
      User name
    </ResponseField>

    <ResponseField name="email" type="string">
      User email
    </ResponseField>

    <ResponseField name="emailVerified" type="boolean">
      Email verification status
    </ResponseField>

    <ResponseField name="image" type="string">
      User avatar URL
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Account creation timestamp
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Last update timestamp
    </ResponseField>

    <ResponseField name="banned" type="boolean">
      Ban status
    </ResponseField>

    <ResponseField name="banReason" type="string">
      Reason for ban (if banned)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of users
</ResponseField>

<ResponseField name="page" type="number">
  Current page number
</ResponseField>

<ResponseField name="limit" type="number">
  Users per page
</ResponseField>

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript SDK theme={null}
  const response = await fetch('/api/admin/users', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'set-role',
      userId: 'user-id',
      role: 'moderator'
    })
  });
  ```
</CodeGroup>

**Request Body:**

<ParamField body="action" type="string" required>
  Must be `"set-role"`
</ParamField>

<ParamField body="userId" type="string" required>
  Target user ID
</ParamField>

<ParamField body="role" type="string" required>
  Role to assign: `"admin"`, `"moderator"`, `"author"`, `"owner"`, `"citizen"`
</ParamField>

### Ban user

Ban a user account.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript SDK theme={null}
  const response = await fetch('/api/admin/users', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'ban',
      userId: 'user-id',
      reason: 'Violation of terms of service'
    })
  });
  ```
</CodeGroup>

**Request Body:**

<ParamField body="action" type="string" required>
  Must be `"ban"`
</ParamField>

<ParamField body="userId" type="string" required>
  User ID to ban
</ParamField>

<ParamField body="reason" type="string">
  Reason for ban (optional but recommended)
</ParamField>

### Unban user

Remove ban from a user account.

```typescript theme={null}
{
  "action": "unban",
  "userId": "user-id"
}
```

### List user sessions

Get all active sessions for a specific user.

```typescript theme={null}
{
  "action": "list-sessions",
  "userId": "user-id"
}
```

**Response:**

```json theme={null}
[
  {
    "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).

```typescript theme={null}
{
  "action": "revoke-sessions",
  "userId": "user-id"
}
```

## Response codes

<ResponseField name="200" type="success">
  Operation successful
</ResponseField>

<ResponseField name="400" type="error">
  Invalid request (missing action, userId, or role)
</ResponseField>

<ResponseField name="403" type="error">
  Forbidden - requires admin role
</ResponseField>

<ResponseField name="404" type="error">
  User not found
</ResponseField>

<ResponseField name="500" type="error">
  Internal server error
</ResponseField>

## Error responses

```json theme={null}
{
  "error": "missing_action"
}
```

```json theme={null}
{
  "error": "missing_userId"
}
```

```json theme={null}
{
  "error": "missing_role"
}
```

```json theme={null}
{
  "error": "unknown_action"
}
```

```json theme={null}
{
  "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

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

## See also

* [User Roles & Permissions](/guides/user-roles)
* [Authentication System](/guides/authentication)
* [Audit Logging](/features/organizations#audit-logging)