Organisation Roles

Replace the permissions of a role

PUT/roles/{id}/permissions
roles:writereplace_role_permissionsDestructiveIdempotent

Makes the ids you send the role's permissions and returns them; [] clears them. An unknown id returns 422 exists on ids.N. With a personal token the permissions you add and the permissions you take away must all be ones you hold yourself, and super admin needs a super admin caller, else 403 missing_permission; permissions that stay are not checked. A service identity is refused only for super admin and super-admin-level permissions. A global role returns 403 forbidden. Adding super admin to a role a SCIM group maps makes the role unassignable by SCIM, and the next SCIM sync takes it from the group's members. Emits role.updated with permissions as the changed field when it changed; sends no email. Also accepts the deprecated {permissions} body until 2027-06-30 (Deprecation, Sunset; not on a missing-scope 403), with dry run and idempotency. Sending the old ids undoes it.

Path parameters

  • idintegerRequired#

    The role's id, a whole number from 1 to 2147483647. An unknown role, another organisation's role and a service role return 404.

Query parameters

  • dry_runboolean#

    Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

  • Idempotency-Keystring#

    Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · RolePermissionReplace

  • idsinteger[]#

    Every permission the role should grant, distinct ids. Send an empty list to clear them.

{
  "ids": [
    12,
    18
  ]
}

Responses

200

Every permission the role grants.

RolePermission[]
{
  "data": [
    {
      "id": 1,
      "key": "string",
      "label": "string"
    }
  ]
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is forbidden when the role is global and so read-only, missing_permission when the caller may not grant, take away or delete what the call touches, with the permissions in details, or one of missing_scope, scope_disabled, org_disabled, ip_blocked, user_disabled.

Error
404

Resource not found (error.code = not_found).

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X PUT https://your-org-domain/kong/core/api/v2/roles/{id}/permissions\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "ids": [
    12,
    18
  ]
}'