# Crear un rol de organización

`POST /fapi/v1/organizations/{org_id}/roles` · llamado desde el host de inicio de sesión del entorno

Crea un rol en la organización, sin permisos; añada los permisos con [Establecer los permisos de un rol](./set-permissions). Una organización puede tener como máximo 50 roles. Requiere la cookie `__Host-idp_session` del usuario autenticado; si la cookie falta, ha caducado o ha sido revocada, devuelve `401 unauthenticated`. Una aplicación propia en otro origen puede enviar en su lugar su token de acceso de la API frontal (`Authorization: DPoP <token>` con una prueba DPoP; véase [Token de acceso de la API frontal](/docs/api/fapi/front-api-token)). El usuario debe ser miembro activo de la organización con el permiso `idp_roles:manage`. Un usuario que no es miembro recibe `404 not_found`, de modo que no se revela la existencia de la organización; un miembro sin el permiso recibe `403 insufficient_permissions`. Los roles de organización deben estar habilitados para el entorno e incluidos en su plan.

## Solicitud

Encabezados:

| Encabezado | Obligatorio | Descripción |
| --- | --- | --- |
| `Idp-Client` | sí | Identificador del SDK. |
| `Origin` | sí | Debe ser exactamente `https://<host de inicio de sesión>`. |
| `Content-Type` | sí | `application/json`. |

`org_id`: el identificador de la organización (`org_…`).

Cuerpo:

| Campo | Obligatorio | Descripción |
| --- | --- | --- |
| `key` | sí | Clave del rol; única en la organización y entre los roles del entorno; no puede cambiarse después. |
| `name` | sí | Nombre visible. |
| `description` | no | Descripción. |

## Respuesta

`201 Created` con los encabezados `Location` y `ETag`; el cuerpo es el rol (véase [Obtener un rol de organización](./get)).

## Errores

| Estado | Código | Cuándo |
| --- | --- | --- |
| 401 | `unauthenticated` | No hay una cookie de sesión válida. |
| 403 | `origin_not_allowed` | `Origin` falta o es incorrecto. |
| 403 | `insufficient_permissions` | El usuario no tiene `idp_roles:manage` en la organización. |
| 403 | `plan_feature_unavailable` | El plan del entorno no incluye los roles de organización (`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | Los roles de organización están desactivados para el entorno. |
| 404 | `not_found` | No existe la organización o el rol para este usuario (un identificador desconocido, mal formado o ajeno recibe la misma respuesta). |
| 409 | `role_key_conflict` | La clave ya se usa en la organización o en un rol del entorno. |
| 409 | `role_limit_reached` | La organización ya tiene 50 roles. |
| 409 | `organization_pending_deletion` | La organización está programada para su eliminación. |
| 422 | `validation_failed` | Falta un campo o no es válido; `errors[]` lo indica. |
| 503 | `service_unavailable` | No disponible temporalmente; reintente después de `Retry-After`. |

## Ejemplo

```bash
curl -X POST https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"key":"auditor","name":"Auditor"}'
```