Create a user with the Java SDK

permit.api.users.create() creates a user, with optional attributes and role assignments, in your Permit environment. This reference is for Java developers who add users to Permit from code. The examples assume an initialized Permit client named permit, as set up in Check permissions with the Java SDK.

To create a user or update the user if the key already exists, use Sync a user with the Java SDK instead.

Signature

UserRead create(UserCreate userData) throws IOException, PermitApiError, PermitContextError

Parameters

Parameter	Type	Required	Description
userData	UserCreate	Yes	The user to create. The fields are listed in UserCreate fields.

UserCreate fields

The UserCreate(key) constructor sets the required key field. Set the optional fields with the with...() builder methods.

Field	Builder method	Type	Required	Description
key	withKey()	String	Yes	A unique ID by which Permit identifies the user in permission checks. Pass the same key to permit.check(). Use any value that is unique in your system, such as an email address or a UUID.
email	withEmail()	String	No	The email address of the user. Unique within the environment.
firstName	withFirstName()	String	No	The first name of the user.
lastName	withLastName()	String	No	The last name of the user.
attributes	withAttributes()	HashMap<String, Object>	No	User attributes for attribute-based access control (ABAC) policies.
roleAssignments	withRoleAssignments()	List<UserRoleCreate>	No	Roles to assign to the user when the user is created. See UserRoleCreate fields.

UserRoleCreate fields

Each UserRoleCreate object describes one role assignment. The UserRoleCreate(role) and UserRoleCreate(role, tenant) constructors set the role and the tenant.

Field	Builder method	Type	Required	Description
role	withRole()	String	Yes	The key or ID of the role to assign.
tenant	withTenant()	String	No	The key or ID of the tenant in which the role is assigned.
resourceInstance	withResourceInstance()	String	No	The resource instance on which the role is assigned, as an ID or in resource_type:resource_instance format.

Example

The example creates a user with a key, an email address, a first and last name, and attributes. The attributes map is a java.util.HashMap.

import io.permit.sdk.openapi.models.UserCreate;
import io.permit.sdk.openapi.models.UserRead;
import java.util.HashMap;

// optional attributes for attribute-based access control
HashMap<String, Object> userAttributes = new HashMap<>();
userAttributes.put("age", Integer.valueOf(50));
userAttributes.put("fav_color", "red");

UserRead user = permit.api.users.create(
    (new UserCreate("auth0|john"))
        .withEmail("john@permit.io")
        .withFirstName("John")
        .withLastName("Smith")
        .withAttributes(userAttributes)
);

Create a user with role assignments

The example creates a user and assigns roles in the same call. The first two assignments grant the editor and moderator roles in the default tenant. The third assignment grants the editor role on one resource instance. The example uses UserRoleCreate from io.permit.sdk.openapi.models and java.util.List and java.util.Arrays.

import io.permit.sdk.openapi.models.UserCreate;
import io.permit.sdk.openapi.models.UserRead;
import io.permit.sdk.openapi.models.UserRoleCreate;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;

// optional attributes for attribute-based access control
HashMap<String, Object> userAttributes = new HashMap<>();
userAttributes.put("age", Integer.valueOf(50));
userAttributes.put("fav_color", "red");

final List<UserRoleCreate> roleAssignments = Arrays.asList(
                new UserRoleCreate("editor", "default"),
                new UserRoleCreate("moderator", "default"),
                new UserRoleCreate("editor", "default").withResourceInstance("myResourceType:myResourceInstance")
        );

UserRead user = permit.api.users.create(
    (new UserCreate("auth0|john"))
        .withEmail("john@permit.io")
        .withFirstName("John")
        .withLastName("Smith")
        .withAttributes(userAttributes)
        .withRoleAssignments(roleAssignments)
);

Return value

create() returns a UserRead object (io.permit.sdk.openapi.models.UserRead) with the created user, including the ID that Permit assigns to the user.

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

• Sync a user with the Java SDK
• Assign a role to a user with the Java SDK
• Fetch a user with the Java SDK
• Sync users