Administrar roles¶

Un rol determina lo que alguien puede hacer. Esta página muestra cómo das un rol a un miembro o a un grupo y cómo lo retiras, cómo haces que un rol valga en las organizaciones que están debajo de la tuya, y cómo creas roles propios. Qué son los roles y qué roles integrados hay está en Roles y acceso.

Dar roles puede hacerlo people-admin (solo member y people-admin) u org-admin; crear, modificar y eliminar roles propios solo puede org-admin. Los roles aún no tienen pantalla en OS: los administras mediante la API. Los ejemplos usan $OS, $TOKEN y $ORG como en Administrar grupos.

Ver los roles¶

curl -s "$OS/api/v1/organisations/$ORG/roles" -H "Authorization: Bearer $TOKEN"

OS muestra primero los roles integrados, con su nombre como id (org-admin), y luego los roles propios, con un id como rol_.... Cada rol muestra sus rules, así que lees exactamente lo que puede hacer un rol integrado con GET .../roles/org-admin.

Dar un rol¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/role-assignments" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"role": "people-admin", "member_id": "mem_..."}'

OS responde 201 con la concesión:

{"id": "ras_...", "role": "people-admin", "member_id": "mem_...", "group_id": null,
 "reach": "organisation", "granted_by": "per_...", "created_at": "2026-10-17T09:12:00Z",
 "allowed_actions": ["see", "use", "write", "delete"]}

• role es el nombre de un rol integrado o el id de un rol propio.
• Indica member_id para un miembro, o group_id para un grupo; entonces todo miembro del grupo tiene el rol.
• reach es organisation (por defecto) o descendants, consulta más abajo.

Solo puedes dar un rol que tengas tú mismo, con al menos el mismo alcance, o del que tengas todas las reglas (por qué). Un miembro tiene como máximo 32 roles, contando member.

GET .../role-assignments?member_id=mem_... o ?group_id=grp_... muestra los roles de un miembro o de un grupo.

Quitar un rol¶

curl -s -X DELETE "$OS/api/v1/organisations/$ORG/role-assignments/ras_..." \
    -H "Authorization: Bearer $TOKEN"

Quitas un rol si tus reglas te permiten dar ese rol (use sobre el rol) y puedes modificar al miembro o al grupo; que tengas tú el rol no importa aquí. Una organización mantiene siempre al menos un miembro activo que tenga org-admin por sí mismo, no mediante un grupo. OS rechaza con 409 una retirada que no deje ninguno; primero da org-admin a otro miembro.

Hacer que un rol valga en las organizaciones de debajo¶

Con "reach": "descendants" el rol vale también en todas las organizaciones que están debajo de la tuya. Así un socio da a sus empleados de soporte acceso a las organizaciones de sus clientes, sin que se hagan miembros de ellas. Solo puedes dar este alcance si tienes tú mismo el rol con alcance descendants. OS rechaza con 409 si una organización de debajo recibiera así más reglas en las funciones de IA de las que puede tener (500), o más de 32 atributos y etiquetas.

curl -s -X POST "$OS/api/v1/organisations/$ORG/role-assignments" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"role": "org-admin", "group_id": "grp_...", "reach": "descendants"}'

Crear un rol propio¶

Un rol propio es un nombre con reglas. Este rol permite a un jefe de equipo ver y administrar a los miembros de su propio departamento:

curl -s -X POST "$OS/api/v1/organisations/$ORG/roles" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"name": "Jefe de equipo", "rules": [
          {"id": "own-department", "effect": "permit", "kind": "membership",
           "actions": ["see", "write"],
           "when": [{"atom": "label_among", "label": "department", "attribute": "department"}]}
        ]}'

La regla dice: un miembro puede ver y modificar a otro miembro si un departamento de ese miembro es también un departamento suyo. Cómo escribes reglas está en Tipos y acciones.

• name es único en la organización y no es el nombre de un rol integrado, como máximo 64 caracteres.
• rules: como máximo 200, cada una con como máximo 15 condiciones.
• labels son opcionales, como en un grupo. La etiqueta builtin es de los roles integrados.
• Una organización tiene como máximo 100 roles propios.

Un rol no puede contener reglas sobre memory_write, share_link, artifact_download, router y egress_host (422): valen para toda la organización y están en el documento de reglas. Una condición nombra role, group, o un atributo que tu organización o una organización superior haya definido.

Debes tener tú mismo cada regla que permite el rol. No se puede escribir una regla que deniegue sobre la administración (organizaciones, miembros, invitaciones, grupos, roles, reglas y atributos); sobre las funciones de IA sí.

Modificar o eliminar un rol propio¶

Sustituyes un rol propio entero con PUT .../roles/rol_... e indicas en If-Match la versión que leíste, como en un grupo. Solo se comprueban frente a lo que tienes tú las reglas que añades: puedes editar un rol que contiene una regla que añadió otra persona. Quien tiene el rol queda sujeto de inmediato a las reglas nuevas.

DELETE .../roles/rol_... elimina el rol y se lo quita a todos los que lo tenían. Los roles integrados no se modifican ni se eliminan.

Si OS rechaza¶