Skip to main content

Create a role with the Java SDK

permit.api.roles.create() creates a role, with optional permissions, in your Permit environment. This reference is for Java developers who define 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 create(RoleCreate roleData) throws IOException, PermitApiError, PermitContextError

Parameters​

ParameterTypeRequiredDescription
roleDataRoleCreateYesThe role to create. The fields are listed in RoleCreate fields.

RoleCreate fields​

The RoleCreate(key, name) constructor sets the two required fields. Set the optional fields with the with...() builder methods.

FieldBuilder methodTypeRequiredDescription
keywithKey()StringYesA URL-friendly name (slug) of the role. Use the key instead of the role ID (UUID) in later calls.
namewithName()StringYesThe display name of the role.
descriptionwithDescription()StringNoWhat the role represents or which permissions it grants.
permissionswithPermissions()List<String>NoThe permissions the role grants, in resource:action format (for example document:read).
attributeswithAttributes()HashMap<String, Object>NoKey-value metadata about the role.
extendswithExtends()List<String>NoKeys of roles that this role extends. The role inherits all permissions of the listed roles.
grantedTowithGrantedTo()DerivedRoleBlockEditNoDerived role rules applied to this role.

Example​

The example creates an admin role that grants the create and read actions on the document resource. The example also uses java.util.ArrayList and java.util.Arrays.

import io.permit.sdk.openapi.models.RoleCreate;
import io.permit.sdk.openapi.models.RoleRead;
import java.util.ArrayList;
import java.util.Arrays;

RoleRead admin = permit.api.roles.create(
	new RoleCreate("admin","Admin")
		.withDescription("an admin role")
		.withPermissions(
			new ArrayList<>(Arrays.asList("document:create", "document:read"))
		)
);

Return value​

create() returns a RoleRead object (io.permit.sdk.openapi.models.RoleRead) with the created role.

Exceptions​

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

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

Contents

Edit this page

Need help?