Set role permissions

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

Replaces the permission set of an organization role. Only permissions the environment allows for organization roles can be used, and administrators can grant only permissions they hold themselves. Permissions and APIs cannot be created 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`.
`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:

Field	Required	Description
`permission_ids`	yes	The full set, at most 100 permission identifiers (`perm_…`); `[]` removes all.

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, or the new set, grants a permission the user does not hold, or the user's own membership carries the role.
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	`permission_not_allowed`	A permission is not allowed for organization roles.
422	`permission_reserved`	A permission is reserved for the platform.
422	`validation_failed`	The list is invalid or too long.
503	`service_unavailable`	Temporarily unavailable; retry after `Retry-After`.

Example

curl -X PUT https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w/permissions \
  -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 '{"permission_ids":["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"]}'