---
sidebar_position: 3
---

# Users and Roles API

The users and roles APIs read known users, read room members, and perform moderation or role changes when granted.

## Required Capabilities

| Method | Capability |
| --- | --- |
| `users.getCurrent()` | `users.read` |
| `users.list()` | `users.read` |
| `users.readMembers()` | `users.read` |
| `users.setRole(userId, role)` | `roles.manage` |
| `users.kick(userId)` | `users.manage` |
| `users.ban(userId, reason?)` | `users.manage` |
| `roles.list()` | `roles.read` |
| `roles.setAssignments(assignments)` | `roles.manage` |

## Read Users

```js
export function activate(context) {
  const currentUser = context.api.users.getCurrent();
  const knownUsers = context.api.users.list();
  const roomMembers = context.api.users.readMembers();

  context.api.logger.info('Room user summary', {
    currentUser: currentUser?.displayName,
    knownUserCount: knownUsers.length,
    memberCount: roomMembers.length
  });
}
```

Example member data:

```json
[
  { "id": "member-1", "userId": "user-alice-01", "displayName": "Alice", "role": "admin" },
  { "id": "member-2", "userId": "user-muse-01", "displayName": "Muse", "role": "member" }
]
```

## Read Roles

```js
export function activate(context) {
  const roles = context.api.roles.list();

  context.api.logger.info('Available roles', roles.map((role) => ({
    id: role.id,
    name: role.name,
    permissions: role.permissions
  })));
}
```

## Set a User Role

```js
export function activate(context) {
  context.api.users.setRole('user-muse-01', 'moderator');
}
```

## Replace Role Assignments

```js
export function activate(context) {
  context.api.roles.setAssignments([
    { userId: 'user-alice-01', roleId: 'admin' },
    { userId: 'user-muse-01', roleId: 'moderator' }
  ]);
}
```

## Kick or Ban a User

```js
export function activate(context) {
  context.api.users.kick('user-spam-01');
  context.api.users.ban('user-spam-02', 'Repeated spam in support channels');
}
```

Moderation calls should normally be behind an explicit user action in plugin UI. Do not run destructive moderation automatically on activation.