# Update an organization role

`PATCH /fapi/v1/organizations/{org_id}/roles/{role_id}` · called from the environment's sign-in host

Changes the name or description of an organization role (JSON merge patch, RFC 7396). Environment roles cannot be changed here. Requires the authenticated user's `__Host-idp_session` cookie; if the cookie is missing, expired, or revoked, returns `401 unauthenticated`. A first-party app on another origin can instead send its front API access token (`Authorization: DPoP <token>` with a DPoP proof; see [Front API access token](/docs/api/fapi/front-api-token)). The user must be an active member of the organization with the `idp_roles:manage` permission. A user who is not a member gets `404 not_found`, so the organization's existence is not disclosed; a member without the permission gets `403 insufficient_permissions`. Organization roles must be enabled for the environment and included in its plan.

## Request

Headers:

| Header | Required | Description |
| --- | --- | --- |
| `Idp-Client` | yes | SDK identifier. |
| `Origin` | yes | Must be exactly `https://<sign-in host>`. |
| `Content-Type` | with a body | `application/json` or `application/merge-patch+json`. |
| `If-Match` | no | `"<version>"` of the role as last read; if the role has changed since, returns `412 precondition_failed` and nothing changes. |

`org_id`: the organization identifier (`org_…`). `role_id`: the role identifier (`rol_…`).

Body (at least one field):

| Field | Required | Description |
| --- | --- | --- |
| `name` | no | New display name. |
| `description` | no | New description. |

## Response

`200 OK` with a new `ETag`; the body is the role (see [Get an organization role](./get)).

## Errors

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | No valid session cookie. |
| 403 | `origin_not_allowed` | `Origin` is missing or wrong. |
| 403 | `insufficient_permissions` | The user lacks `idp_roles:manage` in the organization. |
| 403 | `plan_feature_unavailable` | The environment's plan does not include organization roles (`feature`, `required_plan`). |
| 403 | `org_custom_roles_disabled` | Organization roles are turned off for the environment. |
| 403 | `role_not_assignable` | The role grants a permission the user does not hold, or the user's own membership carries it. |
| 404 | `not_found` | No such organization or organization role for this user; an environment role, an unknown, malformed or foreign identifier answers the same. |
| 409 | `organization_pending_deletion` | The organization is scheduled for deletion. |
| 412 | `precondition_failed` | `If-Match` does not name the current version, or the role changed while the request was processed. |
| 422 | `validation_failed` | A field is invalid, or the patch is empty (`empty_patch`). |
| 503 | `service_unavailable` | Temporarily unavailable; retry after `Retry-After`. |

## Example

```bash
curl -X PATCH https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/merge-patch+json" \
  -H 'If-Match: "1"' \
  -b cookies.txt \
  -d '{"name":"Auditors"}'
```