> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.
# Evaluate ABAC Room Membership
>
Previews which users would be admitted to a private room with the given ABAC attributes, without saving anything. ABAC must be enabled. The request body takes one of two forms:
* **New room**: send `members` and `attributes` (and optionally `excludeSelf`) to preview who would be added when creating an ABAC-managed private room or team. The response sorts the named users into `compliant`, `nonCompliant` and `inconclusive`, and returns the caller's own verdict in `creator`. If the caller does not meet the attributes and `excludeSelf` is not `true`, the request fails with `error-abac-creator-not-admitted`. Permission required: `create-abac-managed-room`. The named users, plus the caller unless `excludeSelf` is `true`, cannot exceed the **API_User_Limit** setting.
* **Existing room**: send `rid` and the proposed `attributes` to preview which current members keep or lose access if the room's attributes change. Results are paginated with the `after` cursor and can be narrowed with `filter` and `group`. Each member has a `verdict`. On the first page, `editor` holds the caller's own verdict when the caller is a member. Permissions required: `abac-management` and `manage-abac-admin-rooms`, or `edit-room-abac-attributes` in that room. Room members without that permission and users who are not room members receive a `403` error.
A member is `compliant` only if they hold every value listed for each key. The existing room form does not accept `count` or `offset` in the body (`error-invalid-params`), and ignores them as query parameters.
Successful new room previews are recorded in the ABAC audit log as an `abac.membership.evaluated` event. Existing room previews and failed requests are not recorded. The endpoint is rate limited to 20 requests every 10 seconds, except for users with the `abac-management` and `manage-abac-admin-rooms` permissions.
ABAC errors such as `error-abac-not-enabled` use the ABAC error contract: the key is returned in both `error` and `errorType`, and `details` names the attribute or cause at fault when there is one. `error-room-not-found` and `error-invalid-attribute-values` return only `error`, without `errorType`.
### Changelog
| Version | Description |
| ------- | ----------- |
| 9.0.0 | Added |
## OpenAPI
````json POST /api/v1/abac/rooms.evaluateMembership
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Rooms"
},
"servers": [
{
"url": "https://apiexplorer.support.rocket.chat"
}
],
"tags": [
{
"name": "Channels"
},
{
"name": "Directory"
},
{
"name": "Groups"
},
{
"name": "Rooms"
},
{
"name": "Teams"
},
{
"name": "Room Invites"
},
{
"name": "Subscriptions"
},
{
"name": "ABAC"
}
],
"paths": {
"/api/v1/abac/rooms.evaluateMembership": {
"post": {
"tags": [
"ABAC"
],
"summary": "Evaluate ABAC Room Membership",
"description": "\n\nPreviews which users would be admitted to a private room with the given ABAC attributes, without saving anything. ABAC must be enabled. The request body takes one of two forms:\n\n* **New room**: send `members` and `attributes` (and optionally `excludeSelf`) to preview who would be added when creating an ABAC-managed private room or team. The response sorts the named users into `compliant`, `nonCompliant` and `inconclusive`, and returns the caller's own verdict in `creator`. If the caller does not meet the attributes and `excludeSelf` is not `true`, the request fails with `error-abac-creator-not-admitted`. Permission required: `create-abac-managed-room`. The named users, plus the caller unless `excludeSelf` is `true`, cannot exceed the **API_User_Limit** setting.\n* **Existing room**: send `rid` and the proposed `attributes` to preview which current members keep or lose access if the room's attributes change. Results are paginated with the `after` cursor and can be narrowed with `filter` and `group`. Each member has a `verdict`. On the first page, `editor` holds the caller's own verdict when the caller is a member. Permissions required: `abac-management` and `manage-abac-admin-rooms`, or `edit-room-abac-attributes` in that room. Room members without that permission and users who are not room members receive a `403` error.\n\nA member is `compliant` only if they hold every value listed for each key. The existing room form does not accept `count` or `offset` in the body (`error-invalid-params`), and ignores them as query parameters.\n\nSuccessful new room previews are recorded in the ABAC audit log as an `abac.membership.evaluated` event. Existing room previews and failed requests are not recorded. The endpoint is rate limited to 20 requests every 10 seconds, except for users with the `abac-management` and `manage-abac-admin-rooms` permissions.\n\nABAC errors such as `error-abac-not-enabled` use the ABAC error contract: the key is returned in both `error` and `errorType`, and `details` names the attribute or cause at fault when there is one. `error-room-not-found` and `error-invalid-attribute-values` return only `error`, without `errorType`.\n\n### Changelog\n| Version | Description |\n| ------- | ----------- |\n| 9.0.0 | Added |",
"operationId": "post-api-v1-abac-rooms.evaluateMembership",
"parameters": [
{
"$ref": "#/components/parameters/Auth-Token"
},
{
"$ref": "#/components/parameters/UserId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"members": {
"type": "array",
"description": "New room form only (required). Usernames of the users to evaluate. Values must be unique.",
"items": {
"type": "string"
},
"example": [
"jane.doe",
"john.roe"
]
},
"excludeSelf": {
"type": "boolean",
"description": "New room form only. If `true`, the caller is not evaluated as a member. Defaults to `false`.",
"default": false,
"example": false
},
"rid": {
"type": "string",
"description": "Existing room form only (required). The ID of the private room whose members you want to evaluate.",
"example": "64f0a1c2b3d4e5f6a7b8c9d0"
},
"attributes": {
"type": "object",
"description": "Required. Map of attribute keys to the values to evaluate. Keys and values can contain letters, digits, `_` and `-`. Each key takes 1 to 10 unique values, and up to 10 keys are allowed.\nIn the new room form, at least one key is required. In the existing room form, an empty object previews clearing all attributes.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"example": {
"clearance": [
"secret"
]
}
},
"filter": {
"type": "string",
"description": "Existing room form only. Text to search members by. Matches the username or the name.",
"example": "jane"
},
"group": {
"type": "string",
"enum": [
"loses",
"retains"
],
"description": "Existing room form only. Return only the members who would lose access (`loses`) or keep it (`retains`).",
"example": "loses"
},
"after": {
"type": "object",
"description": "Existing room form only. The `next` cursor from the previous response, used to fetch the next page.",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
}
},
"example": {
"_id": "aB3dE5fG7hJ9kL1mN",
"username": "jane.doe"
}
}
},
"required": [
"attributes"
]
},
"examples": {
"New room": {
"value": {
"members": [
"jane.doe",
"john.roe"
],
"attributes": {
"clearance": [
"secret"
],
"department": [
"engineering"
]
},
"excludeSelf": false
}
},
"Existing room": {
"value": {
"rid": "64f0a1c2b3d4e5f6a7b8c9d0",
"attributes": {
"clearance": [
"secret"
]
},
"group": "loses"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"compliant": {
"type": "array",
"description": "New room form. Users who would be added.",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"nonCompliant": {
"type": "array",
"description": "New room form. Users who would be skipped.",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"inconclusive": {
"type": "array",
"description": "New room form. Users whose access could not be decided.",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"creator": {
"type": "string",
"description": "New room form. The caller's verdict.",
"enum": [
"compliant",
"nonCompliant",
"inconclusive"
]
},
"members": {
"type": "array",
"description": "Existing room form. The evaluated members on this page.",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
},
"name": {
"type": "string"
},
"verdict": {
"type": "string",
"enum": [
"compliant",
"nonCompliant",
"inconclusive"
]
},
"roles": {
"type": "array",
"description": "The member's room roles, for example `owner`. Omitted for members without a room role.",
"items": {
"type": "string"
}
}
}
}
},
"count": {
"type": "integer",
"description": "Existing room form. Number of members returned on this page."
},
"checked": {
"type": "integer",
"description": "Existing room form. Number of members checked to build this page."
},
"total": {
"type": "integer",
"description": "Existing room form. Total number of room members, when known."
},
"next": {
"type": "object",
"description": "Existing room form. Cursor to pass as `after` for the next page. Absent on the last page.",
"properties": {
"_id": {
"type": "string"
},
"username": {
"type": "string"
}
}
},
"editor": {
"type": "string",
"description": "Existing room form, first page only. The caller's verdict when the caller is a room member.",
"enum": [
"compliant",
"nonCompliant",
"inconclusive"
]
},
"success": {
"type": "boolean"
}
}
},
"examples": {
"New room": {
"value": {
"compliant": [
{
"_id": "aB3dE5fG7hJ9kL1mN",
"username": "jane.doe",
"name": "Jane Doe"
}
],
"nonCompliant": [
{
"_id": "pQ2rS4tU6vW8xY0zA",
"username": "john.roe",
"name": "John Roe"
}
],
"inconclusive": [],
"creator": "compliant",
"success": true
}
},
"Existing room": {
"value": {
"members": [
{
"_id": "pQ2rS4tU6vW8xY0zA",
"username": "john.roe",
"name": "John Roe",
"verdict": "nonCompliant",
"roles": [
"owner"
]
}
],
"count": 1,
"checked": 12,
"total": 12,
"editor": "compliant",
"success": true
}
},
"Existing room, all members": {
"value": {
"members": [
{
"_id": "aB3dE5fG7hJ9kL1mN",
"username": "jane.doe",
"name": "Jane Doe",
"verdict": "compliant",
"roles": [
"owner"
]
},
{
"_id": "pQ2rS4tU6vW8xY0zA",
"username": "john.roe",
"name": "John Roe",
"verdict": "nonCompliant"
}
],
"checked": 2,
"total": 2,
"count": 2,
"editor": "compliant",
"success": true
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
},
"errorType": {
"type": "string"
},
"details": {
"type": "object",
"description": "Present only when a specific attribute or cause is at fault."
}
}
},
"examples": {
"ABAC not enabled": {
"value": {
"success": false,
"error": "error-abac-not-enabled",
"errorType": "error-abac-not-enabled"
}
},
"Too many members": {
"value": {
"success": false,
"error": "error-abac-preview-too-many-members",
"errorType": "error-abac-preview-too-many-members"
}
},
"Value not assignable": {
"value": {
"success": false,
"error": "error-abac-attribute-not-assignable",
"errorType": "error-abac-attribute-not-assignable",
"details": {
"cause": "error-invalid-attribute-values",
"attributes": [
{
"key": "clearance",
"values": [
"topsecret"
]
}
]
}
}
},
"Creator not admitted": {
"value": {
"success": false,
"error": "error-abac-creator-not-admitted",
"errorType": "error-abac-creator-not-admitted"
}
},
"Missing members or rid": {
"value": {
"success": false,
"error": "must have required property 'members'\n must have required property 'rid'\n must match exactly one schema in oneOf",
"errorType": "error-invalid-params"
}
},
"Missing attributes": {
"value": {
"success": false,
"error": "must have required property 'members'\n must have required property 'attributes'\n must match exactly one schema in oneOf",
"errorType": "error-invalid-params"
}
},
"Room not found": {
"value": {
"success": false,
"error": "error-room-not-found"
}
},
"Invalid attribute values": {
"value": {
"success": false,
"error": "error-invalid-attribute-values"
}
},
"Decision unavailable": {
"value": {
"success": false,
"error": "error-abac-decision-unavailable",
"errorType": "error-abac-decision-unavailable"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/authorizationError"
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
}
}
},
"examples": {
"Permission Error": {
"value": {
"success": false,
"error": "User does not have the permissions required for this action [error-unauthorized]"
}
}
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"Auth-Token": {
"name": "X-Auth-Token",
"in": "header",
"description": "The `authToken` of the authenticated user.",
"required": true,
"schema": {
"type": "string"
},
"example": "RScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f"
},
"UserId": {
"name": "X-User-Id",
"in": "header",
"description": "The `userId` of the authenticated user.",
"required": true,
"schema": {
"type": "string"
},
"example": "rbAXPnMktTFbNpwtJ"
}
},
"responses": {
"authorizationError": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
}
}
},
"examples": {
"Authorization Error": {
"value": {
"success": false,
"error": "You must be logged in to do this."
}
}
}
}
}
}
}
}
}
````
![\"Defense\"](\"https://raw.githubusercontent.com/RocketChat/Rocket.Chat-Open-API/main/images/Defense.svg\")