v1

latestOpenAPI 3.0.1GPL v3.02026-07-175524.4 KB

Users

Applies permissions or restrictions to a user.

Applies or removes a user's permissions to one or more rooms.

The request specifies grants (true) or revocations (false) of permissions to apply. Granting or revoking a permission adds a specific override for the given user that overrides the default room permissions.

You can explicitly clear one or more permission setting by specifying a timeout of -1 (in this case the actual true/false value of the permissions are ignored).

Note that the given session ID does not have to exist: it is possible to grant permissions preemptively for a session ID that has never visited the server or room(s).

post/user/{sessionId}/permission

Path parameters

sessionIdstring required

The Session ID is the fixed byte 05 followed by the 32-byte X25519 pubkey used to sign and encrypt messages.

Session ID of a user.

Request body

roomsRoomToken[] required

List of room tokens to which the permissions should be applied. The invoking user must be a moderator (or admin) of all of the given rooms.

timeoutnumber double nullable

How long the new permission (or restriction) should apply, in seconds. If the user already has future permission changes scheduled then they will be cancelled and replaced the changes scheduled here.

When the timeout expires, the specific override will be removed and the user's permission will revert to the room's defaults.

Using a timeout of -1 clears any given permission/restrictions immediately. Note that, in this case, the actual true/false value is ignored. For instance, timeout: -1, read: false and timeout: -1, read: true both clear any existing user-specific permission for read.

readboolean nullable

If true this grants permission to read the room's messages even if the room defaults do not allow reading. If false this restricts permission to read the room's messages even if the room's default allows reading. Specifying this as null will explicitly delete any user-specific read override (effectively returning the user's read permission to the room's default).

accessibleboolean nullable

If true this grants permission to read the room's metadata when the user doesn't have read permission. That is, having this true and read false means the user cannot read messages, but can get information about the room, while both false means the user cannot access any details of the room. Specifying this as null will explicitly delete any user-specific accessible override, returning the user's effective permission to the room's default.

writeboolean nullable

If true this grants permission to post messages to the room, even if the room's default permissions do not allow posting. If false this restricts the user from posting. Specifying this as null will explicitly delete any user-specific write override, returning the user's effective permission to the room's default.

uploadboolean nullable

If true this grants permission to upload files to the room for this user, even if the room's default permission does not allow uploads. If false the user is restricted from uploading files. Specifying as null will explicitly delete any user-specific override, returning the user's effective permission to the room's default.

Example request

{
  "rooms": [
    "session-general"
  ],
  "timeout": 86400,
  "write": true,
  "upload": true
}

Response

Permission update applied successfully.

All 5 operations