Permissions
Preview and change a role's permissions and manage the inheritance rules, with an admin session.
Permission checking and inheritance rule management
Preview impact of a permission change on a role
/api/permissions/admin/servers/{serverId}/roles/{roleId}/impactRead-only endpoint that returns how many members would be affected by adding or removing permissions from a role. Does not modify any data.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
roleId | path | string | yes | Discord role snowflake ID |
Request body (JSON, required): ImpactPreviewDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | Impact preview returned. | ImpactPreviewResponseDto |
400 | Invalid request body. | |
401 | Authentication required. | |
403 | System Admin access required. |
Open in Swagger (opens in a new tab)
Get all permissions assigned to a role
/api/permissions/admin/servers/{serverId}/roles/{roleId}/permissionsReturns the list of permissions currently assigned to a specific role in a server.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
roleId | path | string | yes | Discord role snowflake ID |
Responses
| Status | Description | Body |
|---|---|---|
200 | Role permissions list returned. | RolePermissionsResponseDto |
400 | Invalid path parameter format. | |
401 | Authentication required. | |
403 | System Admin access required. |
Open in Swagger (opens in a new tab)
Add permissions to a role
/api/permissions/admin/servers/{serverId}/roles/{roleId}/permissionsAssigns one or more permissions to a role. Cache is invalidated immediately after the change.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
roleId | path | string | yes | Discord role snowflake ID |
Request body (JSON, required): AssignPermissionsDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | Updated role permissions list returned. | RolePermissionsResponseDto |
400 | Invalid request body. | |
401 | Authentication required. | |
403 | System Admin access required. |
Open in Swagger (opens in a new tab)
Remove a permission from a role
/api/permissions/admin/servers/{serverId}/roles/{roleId}/permissions/{permissionId}Removes a single permission from a role. Executive roles (global or highest-ranking) are protected from modification. Cache is invalidated immediately after the change.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
roleId | path | string | yes | Discord role snowflake ID |
permissionId | path | string | yes | Permission ID to remove |
Responses
| Status | Description | Body |
|---|---|---|
200 | Permission removed successfully. | |
204 | ||
400 | Invalid path parameter format. | |
401 | Authentication required. | |
403 | System Admin access required, or role is protected from modification. |
Open in Swagger (opens in a new tab)
List inheritance rules
/api/permissions/inheritance-rulesReturns all configured role inheritance rules.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
sourceRoleId | query | string | no | Filter by source role ID. |
enabled | query | boolean | no | Filter by enabled status. |
targetScope | query | "all" or "selected" | no | Filter by target scope type. |
serverId | query | string | no | Filter rules that apply to this server (scope=all always matches; scope=selected matches when this server is among targetServerIds). |
Responses
| Status | Description | Body |
|---|---|---|
200 | Inheritance rules list returned. | |
400 | Invalid parameter format. | |
401 | Authentication required. | |
403 | System Admin access required. |
Open in Swagger (opens in a new tab)
Create or update an inheritance rule
/api/permissions/inheritance-rulesUpserts a permission inheritance rule that causes members holding a source role to also receive all permissions of a target role, optionally scoped to a specific server.
Authentication: Admin session token (Authorization: Bearer <token>)
Request body (JSON, required): UpsertInheritanceRuleDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | Inheritance rule upsert result returned. | |
400 | Invalid request body. | |
401 | Authentication required. | |
403 | System Admin access required. |
Open in Swagger (opens in a new tab)
Schemas
AssignPermissionsDto schema
| Field | Type | Required | Description |
|---|---|---|---|
permissionIds | array of number | yes | Array of permission IDs to assign to the role |
ImpactPreviewDto schema
| Field | Type | Required | Description |
|---|---|---|---|
action | "add" or "remove" | yes | Whether to preview adding or removing the permissions |
permissionIds | array of number | yes | Array of permission IDs to preview impact for |
ImpactPreviewResponseDto schema
| Field | Type | Required | Description |
|---|---|---|---|
affectedMembers | number | yes | Number of members affected by the change |
memberIds | array of string | yes | Discord IDs of affected members |
roleHolders | number | yes | Total number of members holding this role |
PermissionItemDto schema
| Field | Type | Required | Description |
|---|---|---|---|
description | string | no | Permission description |
id | number | yes | Permission ID |
key | string | yes | Permission key |
RolePermissionsResponseDto schema
| Field | Type | Required | Description |
|---|---|---|---|
permissions | array of PermissionItemDto | yes | |
roleId | string | yes | Discord role ID |
roleName | string | yes | Role name |
serverId | string | yes | Server ID |
UpsertInheritanceRuleDto schema
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Default: true. |
sourceRoleId | string | yes | Role ID from main server |
targetScope | "all" or "selected" | yes | |
targetServerIds | array of string | no | Required when targetScope = selected |
Source: apps/api/openapi.json.