Toju/docs-site/docs/plugin-development/api/users-and-roles.md

sidebar_position

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

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:

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

Read Roles

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

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

Replace Role Assignments

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

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.