Sync a user with the Java SDK

permit.api.users.sync() creates a user in your Permit environment, or updates the user if a user with the same key already exists. Call sync() when a user signs up or signs in to your application, so the policy decision point (PDP) can evaluate permission checks for that user. This reference is for Java developers who connect their authentication system to Permit. The examples assume an initialized Permit client named permit, as set up in Check permissions with the Java SDK.

note

Don't use sync() to change a user's roles after the first sync. To add or remove a role, call permit.api.users.assignRole() or permit.api.users.unassignRole().

Signature

Overload	Behavior
CreateOrUpdateResult<UserRead> sync(User user)	Takes the same User object (io.permit.sdk.enforcement.User) that permit.check() takes. The SDK copies the key, email, first name, last name, and attributes into a UserCreate object. Role assignments set with withRoleAssignments() on the builder are not sent.
CreateOrUpdateResult<UserRead> sync(UserCreate userData)	Takes a UserCreate object (io.permit.sdk.openapi.models.UserCreate), the same type that permit.api.users.create() takes.

Both overloads throw IOException, PermitApiError, and PermitContextError. The SDK sends the user as an HTTP PUT request to the user's key.

Parameters

Parameter	Type	Required	Description
user	User	Yes, for the User overload	The user to sync. Build the object with new User.Builder(key) and the fields in User fields.
userData	UserCreate	Yes, for the UserCreate overload	The user to sync. The fields are listed in Create a user with the Java SDK.

User fields

The User.Builder(key) constructor sets the required key. Set the optional fields with the with...() builder methods, then call build().

Field	Builder method	Type	Required	Description
key	User.Builder(key)	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.

Example

The example syncs a user with a key, an email address, a first and last name, and attributes, then reads the result. The attributes map is a java.util.HashMap.

import io.permit.sdk.api.models.CreateOrUpdateResult;
import io.permit.sdk.openapi.models.UserRead;
import io.permit.sdk.enforcement.User;
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");

// this is how you sync the user
CreateOrUpdateResult<UserRead> result = permit.api.users.sync(
    (new User.Builder("auth0|john"))
        .withEmail("john@permit.io")
        .withFirstName("John")
        .withLastName("Smith")
        .withAttributes(userAttributes)
        .build()
);
UserRead user = result.getResult();
boolean wasCreated = result.wasCreated();

Return value

sync() returns a CreateOrUpdateResult<UserRead> object (io.permit.sdk.api.models.CreateOrUpdateResult):

Method	Returns
getResult()	The synced user as a UserRead object.
wasCreated()	true if the call created the user (HTTP status 201). false if the call updated an existing 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. If the UserCreate key is null, the SDK throws PermitApiError with response code 406 before calling the API. 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 user with the Java SDK
• Assign a role to a user with the Java SDK
• Delete a user with the Java SDK
• Sync users