Skip to content
Chatto v0.5.0

AdminPermissionService

Chatto exposes this service below /api/connect.

Shared message and enum definitions are documented in Shared Types And Enums.

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.

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/GetRolePermissionTierMatrix

Request a role-permission tier matrix.

FieldTypeDescription
scopePermissionScopeTarget scope. Omit or use SERVER for server scope.

Result: GetRolePermissionTierMatrixResponse

Section titled “Result: GetRolePermissionTierMatrixResponse”

Response containing a role-permission tier matrix.

FieldTypeDescription
matrixTierRolesRequested matrix.

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/GetRolePermissionMatrix

Request one role’s permission matrix.

FieldTypeDescription
role_namestringStable role name.
include_direct_message_scopeboolInclude the direct-message scope column. Defaults to false so an older client does not receive a scope kind that it cannot interpret.
scopePermissionScopeOptional 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.

Response containing one role’s permission matrix.

FieldTypeDescription
matrixRolePermissionMatrixRequested matrix.

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/ListRolePermissionDecisions

Request explicit/effective permission decisions for one role.

FieldTypeDescription
role_namestringStable role name.
include_direct_message_scopeboolInclude direct-message decisions. Defaults to false for older clients.
pagechatto.api.v1.PageRequestScope page. Default 20 scopes, maximum 100. Offsets count scopes, not decisions.
scopePermissionScopeOptional 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.

FieldTypeDescription
role_namestringStable role name.
decisionsrepeated ScopedPermissionDecisionPermission decisions keyed by permission and typed scope.
pagechatto.api.v1.PageInfoTotal matching scopes and whether another scope page exists.
scopesrepeated PermissionScopeScopes in this page, including scopes with no applicable decisions.

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/GetUserPermissionMatrix

Request one user’s permission matrix.

FieldTypeDescription
user_idstringUser ID.
include_direct_message_scopeboolInclude the direct-message scope column. Defaults to false so an older client does not receive a scope kind that it cannot interpret.
scopePermissionScopeOptional 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.

Response containing one user’s permission matrix.

FieldTypeDescription
matrixUserPermissionMatrixRequested matrix.

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/ListUserPermissionDecisions

Request explicit/effective permission decisions for one user.

FieldTypeDescription
user_idstringUser ID.
include_direct_message_scopeboolInclude direct-message decisions. Defaults to false for older clients.
pagechatto.api.v1.PageRequestScope page. Default 20 scopes, maximum 100. Offsets count scopes, not decisions.
scopePermissionScopeOptional 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.

FieldTypeDescription
user_idstringUser ID.
decisionsrepeated ScopedPermissionDecisionPermission decisions keyed by permission and typed scope.
pagechatto.api.v1.PageInfoTotal matching scopes and whether another scope page exists.
scopesrepeated PermissionScopeScopes in this page, including scopes with no applicable decisions.

Explains permission resolution for another user. Requires role.manage.

POST /api/connect/chatto.admin.v1.AdminPermissionService/ExplainPermissions

Request permission explanations for a user at a typed scope.

FieldTypeDescription
user_idstringUser whose permissions should be explained.
room_idstringLegacy room scope. Omit for server-scoped permissions. A request that also supplies scope must identify the same room.
scopePermissionScopeOptional typed target. Use DM with an empty ID for direct messages. Omit for server scope. This field replaces room_id for new clients.

Permission explanations for all permissions applicable at the requested scope.

FieldTypeDescription
explanationsrepeated PermissionExplanationExplanation rows sorted by permission metadata order.

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/SetRolePermission

Request to set one role permission state.

FieldTypeDescription
role_namestringRole name.
permissionstringPermission identifier.
decisionPermissionDecisionNew decision. NONE clears the explicit state.
scopePermissionScopeTarget scope. Omit or use SERVER for server scope.

Result of setting one role permission state.

FieldTypeDescription
decisionPermissionDecisionUpdateUpdated permission decision for the requested role/scope cell.

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/SetUserPermission

Request to set one user permission state.

FieldTypeDescription
user_idstringTarget user ID.
permissionstringPermission identifier.
decisionPermissionDecisionNew decision. NONE clears the explicit state.
scopePermissionScopeTarget scope. Omit or use SERVER for server scope.

Result of setting one user permission state.

FieldTypeDescription
decisionPermissionDecisionUpdateUpdated permission decision for the requested user/scope cell.