Evaluate ABAC Room Membership

Post

/api/v1/abac/rooms.evaluateMembership

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

Header parameters

X-Auth-Token

stringRequired

The authToken of the authenticated user.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f

X-User-Id

stringRequired

The userId of the authenticated user.

ExamplerbAXPnMktTFbNpwtJ

Body parameters

New room

{
  "members": [
    "jane.doe",
    "john.roe"
  ],
  "attributes": {
    "clearance": [
      "secret"
    ],
    "department": [
      "engineering"
    ]
  },
  "excludeSelf": false
}

Expand All

object

members

Array of string

New room form only (required). Usernames of the users to evaluate. Values must be unique.

Example[ "jane.doe", "john.roe" ]

string

excludeSelf

boolean

New room form only. If true, the caller is not evaluated as a member. Defaults to false.

Defaultfalse

Examplefalse

rid

string

Existing room form only (required). The ID of the private room whose members you want to evaluate.

Example64f0a1c2b3d4e5f6a7b8c9d0

attributes

object Required

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. In the new room form, at least one key is required. In the existing room form, an empty object previews clearing all attributes.

Example{ "clearance": [ "secret" ] }

property*

Array of string additionalProperties

string

filter

string

Existing room form only. Text to search members by. Matches the username or the name.

Examplejane

group

string

Existing room form only. Return only the members who would lose access (loses) or keep it (retains).

Valid values[ "loses", "retains" ]

Exampleloses

after

object

Existing room form only. The next cursor from the previous response, used to fetch the next page.

Example{ "_id": "aB3dE5fG7hJ9kL1mN", "username": "jane.doe" }

_id

string

username

string

Responses

200

New room

{
  "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

{
  "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

{
  "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
}

Expand All

object

compliant

Array of object

New room form. Users who would be added.

object

_id

string

username

string

name

string

nonCompliant

Array of object

New room form. Users who would be skipped.

object

_id

string

username

string

name

string

inconclusive

Array of object

New room form. Users whose access could not be decided.

object

_id

string

username

string

name

string

creator

string

New room form. The caller's verdict.

Valid values[ "compliant", "nonCompliant", "inconclusive" ]

members

Array of object

Existing room form. The evaluated members on this page.

object

_id

string

username

string

name

string

verdict

string

Valid values[ "compliant", "nonCompliant", "inconclusive" ]

roles

Array of string

The member's room roles, for example owner. Omitted for members without a room role.

string

count

integer

Existing room form. Number of members returned on this page.

checked

integer

Existing room form. Number of members checked to build this page.

total

integer

Existing room form. Total number of room members, when known.

object

Existing room form. Cursor to pass as after for the next page. Absent on the last page.

_id

string

username

string

editor

string

Existing room form, first page only. The caller's verdict when the caller is a room member.

Valid values[ "compliant", "nonCompliant", "inconclusive" ]

success

boolean

400

Bad Request

ABAC not enabled

{
  "success": false,
  "error": "error-abac-not-enabled",
  "errorType": "error-abac-not-enabled"
}

Value not assignable

{
  "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"
        ]
      }
    ]
  }
}

Missing members or rid

{
  "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

{
  "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"
}

Expand All

object

success

boolean

error

string

errorType

string

details

object

Present only when a specific attribute or cause is at fault.

401

Unauthorized

Authorization Error

{
  "success": false,
  "error": "You must be logged in to do this."
}

object

success

boolean

error

string

403

Forbidden

Permission Error

{
  "success": false,
  "error": "User does not have the permissions required for this action [error-unauthorized]"
}

object

success

boolean

error

string

Was this article helpful?