---
title: "Applies permissions or restrictions to a user."
method: POST
path: "/user/{sessionId}/permission"
tags: ["Users"]
---

# Applies permissions or restrictions to a user.

`POST /user/{sessionId}/permission`

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

## Path parameters

- `sessionId` string, required — The Session ID is the fixed byte `05` followed by the 32-byte X25519 pubkey used to sign and encrypt messages.

## Request body

- object
  - `rooms` RoomToken[], 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.
  - `timeout` number, 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`.
  - `read` boolean, 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).
  - `accessible` boolean, 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.
  - `write` boolean, 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.
  - `upload` boolean, 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.

## Response `200`

Permission update applied successfully.

## Other responses

- `403` — Permission denied. The user attempting to set the permissions does not have moderator permissions for one or more of the given rooms.

## Changes

- **2022-02-14** `24e7e4a6482f` — 1 info
  - added the new optional request property `accessible`
- **2021-11-10** `fbd68862ef17` — 1 warning
  - removed the request property `accessible`

[Change history](https://skmtc.dev/oxen-io/apis/session-open-group-server/changes/user/:sessionId/permission/post.md)

---

[API](https://skmtc.dev/oxen-io/apis/session-open-group-server.md) · [All operations](https://skmtc.dev/oxen-io/apis/session-open-group-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/oxen-io/session-open-group-server/revisions/39a4ebc32b95/schema)