role

El dominio role tiene 8 acciones. En la superficie meta se alcanzan todas a través de arcane_role; en la individual, cada una es una herramienta propia; en la dinámica se ejecutan con arcane_execute_action y el ID canónico.

Resumen

Acción	Título	Tipo
role.create	Create a custom role	escritura
role.delete	Delete a custom role	destructiva
role.get	Get a role	lectura
role.list	List roles	lectura
role.permissions	Get the permission manifest	lectura
role.update	Update a custom role	escritura
role.user_assignments_get	List a user’s role assignments	lectura
role.user_assignments_set	Replace a user’s manual role assignments	destructiva

Acciones

role.create

Create a custom role

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

• Tipo: escritura
• Parámetros obligatorios: name, permissions
• Meta-herramienta: arcane_role con "action": "create"
• Herramienta individual: arcane_role_create
• Ruta de Arcane: POST /api/roles
• ID de operación: create-role
• Uso: 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.
• Acciones relacionadas: 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.

• Tipo: destructiva — exige confirm: true
• Parámetros obligatorios: id
• Meta-herramienta: arcane_role con "action": "delete"
• Herramienta individual: arcane_role_delete
• Ruta de Arcane: DELETE /api/roles/{id}
• ID de operación: delete-role
• Uso: 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.
• Acciones relacionadas: role.list, role.get, federated_credential.list, oidc.role_mapping_list

role.get

Get a role

• Tipo: lectura
• Parámetros obligatorios: id
• Meta-herramienta: arcane_role con "action": "get"
• Herramienta individual: arcane_role_get
• Ruta de Arcane: GET /api/roles/{id}
• ID de operación: get-role
• Uso: 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.
• Acciones relacionadas: role.list, role.update, role.delete

role.list

List roles

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

• Tipo: lectura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_role con "action": "list"
• Herramienta individual: arcane_role_list
• Ruta de Arcane: GET /api/roles
• ID de operación: list-roles
• Uso: 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.
• Acciones relacionadas: 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.

• Tipo: lectura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_role con "action": "permissions"
• Herramienta individual: arcane_role_permissions
• Ruta de Arcane: GET /api/roles/available-permissions
• ID de operación: get-permissions-manifest
• Uso: 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.
• Acciones relacionadas: 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.

• Tipo: escritura
• Parámetros obligatorios: id, name, permissions
• Meta-herramienta: arcane_role con "action": "update"
• Herramienta individual: arcane_role_update
• Ruta de Arcane: PUT /api/roles/{id}
• ID de operación: update-role
• Uso: 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.
• Acciones relacionadas: role.get, role.permissions, role.list

role.user_assignments_get

List a user’s role assignments

Reserved for global admins.

• Tipo: lectura
• Parámetros obligatorios: userId
• Meta-herramienta: arcane_role con "action": "user_assignments_get"
• Herramienta individual: arcane_role_user_assignments_get
• Ruta de Arcane: GET /api/users/{userId}/role-assignments
• ID de operación: list-user-role-assignments
• Uso: 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.
• Acciones relacionadas: 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.

• Tipo: destructiva — exige confirm: true
• Parámetros obligatorios: userId, assignments
• Meta-herramienta: arcane_role con "action": "user_assignments_set"
• Herramienta individual: arcane_role_user_assignments_set
• Ruta de Arcane: PUT /api/users/{userId}/role-assignments
• ID de operación: set-user-role-assignments
• Uso: 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.
• Acciones relacionadas: role.user_assignments_get, role.list, user.list, environment.list