89 lines
2.1 KiB
Markdown
89 lines
2.1 KiB
Markdown
---
|
|
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. |