AdminPermissionService
Chatto exposes this service below /api/connect.
Shared message and enum definitions are documented in Shared Types And Enums.
AdminPermissionService
Section titled “AdminPermissionService”Provides permission reads and admin permission writes. Matrices return all matching scopes. Decision lists return scope pages. Both use the order SERVER, DM, then each GROUP followed by its ROOM scopes. Groups and rooms follow the configured sidebar order. Only matching scopes are evaluated. Decision pages are live reads; layout or visibility changes can shift offsets. Keep the same filters on each request and advance by the number of returned scopes. A scope filter of DM selects DM even when include_direct_message_scope is false.
GetRolePermissionTierMatrix
Section titled “GetRolePermissionTierMatrix”Gets the role-permission matrix for a single tier. Server scope requires role.manage; group and room scopes require role.manage or effective room.manage at the requested resource.
POST /api/connect/chatto.admin.v1.AdminPermissionService/GetRolePermissionTierMatrixInput: GetRolePermissionTierMatrixRequest
Section titled “Input: GetRolePermissionTierMatrixRequest”Request a role-permission tier matrix.
| Field | Type | Description |
|---|---|---|
scope | PermissionScope | Target scope. Omit or use SERVER for server scope. |
Result: GetRolePermissionTierMatrixResponse
Section titled “Result: GetRolePermissionTierMatrixResponse”Response containing a role-permission tier matrix.
| Field | Type | Description |
|---|---|---|
matrix | TierRoles | Requested matrix. |
GetRolePermissionMatrix
Section titled “GetRolePermissionMatrix”Gets a complete role permission matrix. Requires role.manage. Returns NOT_FOUND when the role does not exist.
POST /api/connect/chatto.admin.v1.AdminPermissionService/GetRolePermissionMatrixInput: GetRolePermissionMatrixRequest
Section titled “Input: GetRolePermissionMatrixRequest”Request one role’s permission matrix.
| Field | Type | Description |
|---|---|---|
role_name | string | Stable role name. |
include_direct_message_scope | bool | Include the direct-message scope column. Defaults to false so an older client does not receive a scope kind that it cannot interpret. |
scope | PermissionScope | Optional exact scope filter. Omit to read all scopes. Missing or inaccessible scopes produce an empty matrix. SERVER and DM require an empty ID; GROUP and ROOM require an ID. |
Result: GetRolePermissionMatrixResponse
Section titled “Result: GetRolePermissionMatrixResponse”Response containing one role’s permission matrix.
| Field | Type | Description |
|---|---|---|
matrix | RolePermissionMatrix | Requested matrix. |
ListRolePermissionDecisions
Section titled “ListRolePermissionDecisions”Lists one role’s permission decisions as resource-oriented rows. Requires role.manage. Returns NOT_FOUND when the role does not exist.
POST /api/connect/chatto.admin.v1.AdminPermissionService/ListRolePermissionDecisionsInput: ListRolePermissionDecisionsRequest
Section titled “Input: ListRolePermissionDecisionsRequest”Request explicit/effective permission decisions for one role.
| Field | Type | Description |
|---|---|---|
role_name | string | Stable role name. |
include_direct_message_scope | bool | Include direct-message decisions. Defaults to false for older clients. |
page | chatto.api.v1.PageRequest | Scope page. Default 20 scopes, maximum 100. Offsets count scopes, not decisions. |
scope | PermissionScope | Optional exact scope filter. Missing or inaccessible scopes produce an empty page. SERVER and DM require an empty ID; GROUP and ROOM require an ID. |
Result: ListRolePermissionDecisionsResponse
Section titled “Result: ListRolePermissionDecisionsResponse”Resource-oriented permission decisions for one role.
| Field | Type | Description |
|---|---|---|
role_name | string | Stable role name. |
decisions | repeated ScopedPermissionDecision | Permission decisions keyed by permission and typed scope. |
page | chatto.api.v1.PageInfo | Total matching scopes and whether another scope page exists. |
scopes | repeated PermissionScope | Scopes in this page, including scopes with no applicable decisions. |
GetUserPermissionMatrix
Section titled “GetUserPermissionMatrix”Gets a complete user permission matrix. Human targets require user.manage-permissions; bot targets require ownership or bot.manage. Returns NOT_FOUND when the user does not exist.
POST /api/connect/chatto.admin.v1.AdminPermissionService/GetUserPermissionMatrixInput: GetUserPermissionMatrixRequest
Section titled “Input: GetUserPermissionMatrixRequest”Request one user’s permission matrix.
| Field | Type | Description |
|---|---|---|
user_id | string | User ID. |
include_direct_message_scope | bool | Include the direct-message scope column. Defaults to false so an older client does not receive a scope kind that it cannot interpret. |
scope | PermissionScope | Optional exact scope filter. Omit to read all scopes. Missing or inaccessible scopes produce an empty matrix. SERVER and DM require an empty ID; GROUP and ROOM require an ID. |
Result: GetUserPermissionMatrixResponse
Section titled “Result: GetUserPermissionMatrixResponse”Response containing one user’s permission matrix.
| Field | Type | Description |
|---|---|---|
matrix | UserPermissionMatrix | Requested matrix. |
ListUserPermissionDecisions
Section titled “ListUserPermissionDecisions”Lists one user’s permission decisions as resource-oriented rows. Human targets require user.manage-permissions; bot targets require ownership or bot.manage. Returns NOT_FOUND when the user does not exist.
POST /api/connect/chatto.admin.v1.AdminPermissionService/ListUserPermissionDecisionsInput: ListUserPermissionDecisionsRequest
Section titled “Input: ListUserPermissionDecisionsRequest”Request explicit/effective permission decisions for one user.
| Field | Type | Description |
|---|---|---|
user_id | string | User ID. |
include_direct_message_scope | bool | Include direct-message decisions. Defaults to false for older clients. |
page | chatto.api.v1.PageRequest | Scope page. Default 20 scopes, maximum 100. Offsets count scopes, not decisions. |
scope | PermissionScope | Optional exact scope filter. Missing or inaccessible scopes produce an empty page. SERVER and DM require an empty ID; GROUP and ROOM require an ID. |
Result: ListUserPermissionDecisionsResponse
Section titled “Result: ListUserPermissionDecisionsResponse”Resource-oriented permission decisions for one user.
| Field | Type | Description |
|---|---|---|
user_id | string | User ID. |
decisions | repeated ScopedPermissionDecision | Permission decisions keyed by permission and typed scope. |
page | chatto.api.v1.PageInfo | Total matching scopes and whether another scope page exists. |
scopes | repeated PermissionScope | Scopes in this page, including scopes with no applicable decisions. |
ExplainPermissions
Section titled “ExplainPermissions”Explains permission resolution for another user. Requires role.manage.
POST /api/connect/chatto.admin.v1.AdminPermissionService/ExplainPermissionsInput: ExplainPermissionsRequest
Section titled “Input: ExplainPermissionsRequest”Request permission explanations for a user at a typed scope.
| Field | Type | Description |
|---|---|---|
user_id | string | User whose permissions should be explained. |
room_id | string | Legacy room scope. Omit for server-scoped permissions. A request that also supplies scope must identify the same room. |
scope | PermissionScope | Optional typed target. Use DM with an empty ID for direct messages. Omit for server scope. This field replaces room_id for new clients. |
Result: ExplainPermissionsResponse
Section titled “Result: ExplainPermissionsResponse”Permission explanations for all permissions applicable at the requested scope.
| Field | Type | Description |
|---|---|---|
explanations | repeated PermissionExplanation | Explanation rows sorted by permission metadata order. |
SetRolePermission
Section titled “SetRolePermission”Sets one role permission decision. Server scope requires role.manage; group and room scopes also accept effective room.manage at that resource.
POST /api/connect/chatto.admin.v1.AdminPermissionService/SetRolePermissionInput: SetRolePermissionRequest
Section titled “Input: SetRolePermissionRequest”Request to set one role permission state.
| Field | Type | Description |
|---|---|---|
role_name | string | Role name. |
permission | string | Permission identifier. |
decision | PermissionDecision | New decision. NONE clears the explicit state. |
scope | PermissionScope | Target scope. Omit or use SERVER for server scope. |
Result: SetRolePermissionResponse
Section titled “Result: SetRolePermissionResponse”Result of setting one role permission state.
| Field | Type | Description |
|---|---|---|
decision | PermissionDecisionUpdate | Updated permission decision for the requested role/scope cell. |
SetUserPermission
Section titled “SetUserPermission”Sets one user permission decision. Human targets require user.manage-permissions; bot targets require ownership or bot.manage and accept only allow or clear within the bot owner’s current authority.
POST /api/connect/chatto.admin.v1.AdminPermissionService/SetUserPermissionInput: SetUserPermissionRequest
Section titled “Input: SetUserPermissionRequest”Request to set one user permission state.
| Field | Type | Description |
|---|---|---|
user_id | string | Target user ID. |
permission | string | Permission identifier. |
decision | PermissionDecision | New decision. NONE clears the explicit state. |
scope | PermissionScope | Target scope. Omit or use SERVER for server scope. |
Result: SetUserPermissionResponse
Section titled “Result: SetUserPermissionResponse”Result of setting one user permission state.
| Field | Type | Description |
|---|---|---|
decision | PermissionDecisionUpdate | Updated permission decision for the requested user/scope cell. |