Update a role with the Java SDK

permit.api.roles.update() changes the fields you set on an existing role and leaves the other fields unchanged. This reference is for Java developers who manage role-based access control (RBAC) roles from code. The examples assume an initialized Permit client named permit, as set up in Check permissions with the Java SDK.

Signature

RoleRead update(String roleKey, RoleUpdate roleData) throws IOException, PermitApiError, PermitContextError

Parameters

Parameter	Type	Required	Description
roleKey	String	Yes	The key or the ID (UUID) of the role. The Permit API accepts either value.
roleData	RoleUpdate	Yes	The fields to change. The fields are listed in RoleUpdate fields.

RoleUpdate fields

Create a RoleUpdate with the no-argument constructor and set only the fields you want to change. Every field is optional. The SDK sends the update as an HTTP PATCH request.

Field	Builder method	Type	Description
name	withName()	String	The display name of the role.
description	withDescription()	String	What the role represents or which permissions it grants.
permissions	withPermissions()	List<String>	The permissions the role grants, in resource:action format (for example document:read).
attributes	withAttributes()	HashMap<String, Object>	Key-value metadata about the role.
extends	withExtends()	List<String>	Keys of roles that this role extends. The role inherits all permissions of the listed roles.
grantedTo	withGrantedTo()	DerivedRoleBlockEdit	Derived role rules applied to this role.

To add or remove permissions without replacing the full list, the SDK also has permit.api.roles.assignPermissions(roleKey, permissions) and permit.api.roles.removePermissions(roleKey, permissions). Both methods take an ArrayList<String> and return a RoleRead.

Example

The example changes the description of the admin role.

import io.permit.sdk.openapi.models.RoleUpdate;

permit.api.roles.update("admin", new RoleUpdate().withDescription("new description"));

Return value

update() returns a RoleRead object (io.permit.sdk.openapi.models.RoleRead) with the updated role.

Exceptions

All exception classes except IOException are in the io.permit.sdk.api package.

Exception	Thrown when
IOException	The HTTP request to the Permit API fails, for example because of a network error.
PermitApiError	The Permit API returns an error status code. getResponseCode() returns the HTTP status code and getRawResponse() returns the response body.
PermitContextError	The SDK context does not include an environment, for example because the API key is scoped to an organization or project.

Related methods

• Create a role with the Java SDK
• Fetch a role with the Java SDK
• Delete a role with the Java SDK