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). 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).
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
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"}'