role

The role domain has 8 actions. On the meta surface they are all reached through arcane_role; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
role.create	Create a custom role	write
role.delete	Delete a custom role	destructive
role.get	Get a role	read
role.list	List roles	read
role.permissions	Get the permission manifest	read
role.update	Update a custom role	write
role.user_assignments_get	List a user’s role assignments	read
role.user_assignments_set	Replace a user’s manual role assignments	destructive

Actions

role.create

Create a custom role

Built-in roles cannot be created via this endpoint. Only custom roles are accepted. Reserved for global admins.

• Kind: write
• Required parameters: name, permissions
• Meta tool: arcane_role with "action": "create"
• Individual tool: arcane_role_create
• Arcane route: POST /api/roles
• Operation ID: create-role
• Usage: Global admins only. Creates a custom role from name (unique, else 409), optional description and permissions (at least one string from role.permissions, unknown ones answer 400). A role has no effect until assigned: role.user_assignments_set for a user, oidc.role_mapping_create for an OIDC claim, or a federated credential’s roleId. Returns the role with its id.
• Related actions: role.permissions, role.user_assignments_set, oidc.role_mapping_create, federated_credential.create

role.delete

Delete a custom role

Built-in roles are protected. Deleting cascades all user assignments. Reserved for global admins.

• Kind: destructive — requires confirm: true
• Required parameters: id
• Meta tool: arcane_role with "action": "delete"
• Individual tool: arcane_role_delete
• Arcane route: DELETE /api/roles/{id}
• Operation ID: delete-role
• Usage: Global admins only. Deletes a custom role (id from role.list). Built-in roles answer 403. Every user assignment and OIDC role mapping using the role is removed with it, so its holders lose those permissions. Fails with 409 while a federated credential still uses the role as its roleId (repoint or delete that credential first) and when deleting it would leave no user with global admin.
• Related actions: role.list, role.get, federated_credential.list, oidc.role_mapping_list

role.get

Get a role

• Kind: read
• Required parameters: id
• Meta tool: arcane_role with "action": "get"
• Individual tool: arcane_role_get
• Arcane route: GET /api/roles/{id}
• Operation ID: get-role
• Usage: One role by id (from role.list, or a roleId in role.user_assignments_get): name, description, full permissions list, builtIn and assignedUserCount. Not found answers 404. Needs roles:read.
• Related actions: role.list, role.update, role.delete

role.list

List roles

Get a paginated list of roles (built-in + custom)

• Kind: read
• Required parameters: none
• Meta tool: arcane_role with "action": "list"
• Individual tool: arcane_role_list
• Arcane route: GET /api/roles
• Operation ID: list-roles
• Usage: Paginated roles: the built-in ones (Admin, Editor, No-Shell Editor, Deployer, Monitor, Viewer: builtIn=true, cannot be edited or deleted) and custom ones, each with id, permissions and assignedUserCount. search matches name or description, and start/limit page. Needs roles:list. The id is the roleId used by role.user_assignments_set, oidc.role_mapping_create and federated credentials.
• Related actions: role.get, role.create, role.user_assignments_set, role.permissions

role.permissions

Get the permission manifest

Returns every permission the server recognizes, grouped by resource. Used by permission-picking UIs.

• Kind: read
• Required parameters: none
• Meta tool: arcane_role with "action": "permissions"
• Individual tool: arcane_role_permissions
• Arcane route: GET /api/roles/available-permissions
• Operation ID: get-permissions-manifest
• Usage: Every permission string the server recognizes (resource:action, e.g. containers:list), grouped by resource with scope global or env, each with the permissions it requires (e.g. settings:read), plus presets (editor, global-admin). Any authenticated caller may read it. Use it before writing a role or a scoped API key: role.create and role.update answer 400 on an unknown permission string, and api_key.create refuses one with 403.
• Related actions: role.create, role.update, api_key.create

role.update

Update a custom role

Built-in roles are read-only and return 403 on update. Reserved for global admins.

• Kind: write
• Required parameters: id, name, permissions
• Meta tool: arcane_role with "action": "update"
• Individual tool: arcane_role_update
• Arcane route: PUT /api/roles/{id}
• Operation ID: update-role
• Usage: Global admins only. Replaces the name and the whole permissions list (both required, so send the full list and read it with role.get first). description is replaced too: omitting it clears the stored description, so resend it to keep it. Built-in roles answer 403, a duplicate name 409, unknown permissions 400, and 409 when the change would leave no user with global admin. Users holding the role get the change within seconds.
• Related actions: role.get, role.permissions, role.list

role.user_assignments_get

List a user’s role assignments

Reserved for global admins.

• Kind: read
• Required parameters: userId
• Meta tool: arcane_role with "action": "user_assignments_get"
• Individual tool: arcane_role_user_assignments_get
• Arcane route: GET /api/users/{userId}/role-assignments
• Operation ID: list-user-role-assignments
• Usage: Global admins only. A user’s role assignments (userId from user.list), each with roleId, source (manual or oidc) and environmentId (absent for a global grant). An unknown userId returns an empty list, not 404. auth.me shows the caller’s own.
• Related actions: role.user_assignments_set, role.get, user.list, auth.me

role.user_assignments_set

Replace a user’s manual role assignments

Replaces every source=‘manual’ assignment for the user. source=‘oidc’ assignments are not touched. Reserved for global admins. Enforces the last-admin guard.

• Kind: destructive — requires confirm: true
• Required parameters: userId, assignments
• Meta tool: arcane_role with "action": "user_assignments_set"
• Individual tool: arcane_role_user_assignments_set
• Arcane route: PUT /api/users/{userId}/role-assignments
• Operation ID: set-user-role-assignments
• Usage: Global admins only. This is how a user gets permissions. Replaces all of the user’s manual assignments with assignments ([{roleId, environmentId?}]: roleId from role.list, environmentId from environment.list, omitted for a global grant). [] removes them all, OIDC-sourced assignments stay. Unknown role or environment answers 400, unknown user 404, and 409 if no global admin would remain. Returns the user’s resulting assignments.
• Related actions: role.user_assignments_get, role.list, user.list, environment.list