User Account API Basics

Documentation Menu
Go Back

User Account API Basics

You can Add and manage Users from the Control Panel, but you can also use Liferay’s REST APIs. You can call these services to add, edit, delete Users.

Start with adding a new User.

Adding Users

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.75-ga75

Sign in to Liferay at http://localhost:8080. Use the email address [email protected] and the password test. When prompted, change the password to learn.

Then, follow these steps:

  1. Download and unzip User Account API Basics.

    curl https://resources.learn.liferay.com/dxp/latest/en/users-and-permissions/developer-guide/liferay-y6q4.zip -O

    unzip liferay-y6q4.zip

  2. Use the cURL script to add a new User to your Liferay instance. On the command line, navigate to the curl folder. Execute the User_POST_ToInstance.sh script.

    ./User_POST_ToInstance.sh

    The JSON response shows a new User has been added:

    {
  "additionalName": "",
  "alternateName": "able",
  "birthDate": "1977-01-01T00:00:00Z",
  "customFields": [],
  "dashboardURL": "",
  "dateCreated": "2021-05-19T16:04:46Z",
  "dateModified": "2021-05-19T16:04:46Z",
  "emailAddress": "[email protected]",
  "familyName": "Foo",
  "givenName": "Able",
  "id": 39321,
  "jobTitle": "",
  "keywords": [],
  "name": "Able Foo",
  "organizationBriefs": [],
  "profileURL": "",
  "roleBriefs": [
    {
      "id": 20113,
      "name": "User"
    }
  ],
  "siteBriefs": [
    {
      "id": 20127,
      "name": "Global"
    },
    {
      "id": 20125,
      "name": "Guest"
    }
  ],
  "userAccountContactInformation": {
    "emailAddresses": [],
    "facebook": "",
    "jabber": "",
    "postalAddresses": [],
    "skype": "",
    "sms": "",
    "telephones": [],
    "twitter": "",
    "webUrls": []
  }
}%

    In Control Panel, verify the newly added User. Note the User’s id number for later commands.

    See the added User in Control Panel.

  3. The REST service can also be called with a Java class. Navigate out of the curl folder and into the java folder. Compile the source files with the following command:

    javac -classpath .:* *.java

  4. Run the User_POST_ToInstance class with the following command:

    java -classpath .:* User_POST_ToInstance

    Verify in Control Panel that another User has been added.

    In Control Panel, another User has been added.

Read on to see how the cURL command and Java class work.

Examine the cURL Command

The User_POST_ToInstance.sh script calls the REST service with a cURL command.

curl \
	-H "Content-Type: application/json" \
	-X POST \
	"http://localhost:8080/o/headless-admin-user/v1.0/user-accounts" \
	-d "{\"alternateName\": \"Able\", \"emailAddress\": \"[email protected]\", \"familyName\": \"Foo\", \"givenName\": \"Able\"}" \
	-u "[email protected]:learn"

Here are the command’s arguments:

Arguments Description
-H "Content-Type: application/json" Indicates that the request body format is JSON.
-X POST The HTTP method to invoke at the specified endpoint
"http://localhost:8080/o/headless-admin-user/v1.0/user-accounts" The REST service endpoint
-d "{\"alternateName\": \"Able\", \"emailAddress\": \"[email protected]\", \"familyName\": \"Foo\", \"givenName\": \"Able\"}" The data you are requesting to post
-u "[email protected]:learn" Basic authentication credentials
note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application that uses OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The User_POST_ToInstance.java class adds a User by calling the user related service.

public static void main(String[] args) throws Exception {
	UserAccountResource.Builder builder = UserAccountResource.builder();

	UserAccountResource userAccountResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	UserAccount userAccount = userAccountResource.postUserAccount(
		new UserAccount() {
			{
				alternateName = "Baker";
				emailAddress = "[email protected]";
				familyName = "Foo";
				givenName = "Baker";
			}
		});

	System.out.println(userAccount);
}

The class calls the REST service with only three lines of code:

Line (abbreviated) Description
UserAccountResource.Builder builder = ... Gets a Builder for generating a UserAccountResource service instance.
UserAccountResource userAccountResource = builder.authentication(...).build() Specifies basic authentication and generates a UserAccountResources service instance.
UserAccount userAccount = userAccountResource.postUserAccount(...) Calls the userAccountResource.postUserAccount method and passes the data to post.

Note that the project includes the com.liferay.headless.admin.user.client.jar file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api.

note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one but call different UserAccountResource methods.

important

See UserAccountResource for service details.

Below are examples of calling the other User REST services using cURL and Java.

Get Instance Users

Get a list of all Users with the following cURL and Java commands.

Users_GET_FromInstance.sh

Command:

./Users_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/user-accounts" \
	-u "[email protected]:learn"

Users_GET_FromInstance.java

Command:

java -classpath .:* Users_GET_FromInstance

Code:

public static void main(String[] args) throws Exception {
	UserAccountResource.Builder builder = UserAccountResource.builder();

	UserAccountResource userAccountResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	Page<UserAccount> page = userAccountResource.getUserAccountsPage(
		null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

All the Users of the instance are listed in the JSON response.

Get a User

Get a specific User with the following cURL and Java commands. Note, replace 1234 with your User’s ID.

User_GET_ById.sh

Command:

./User_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/user-accounts/${1}" \
	-u "[email protected]:learn"

User_GET_ById.java

Command:

java -classpath .:* -DuserId=1234 User_GET_ById

Code:

public static void main(String[] args) throws Exception {
	UserAccountResource.Builder builder = UserAccountResource.builder();

	UserAccountResource userAccountResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	System.out.println(
		userAccountResource.getUserAccount(
			Long.valueOf(System.getProperty("userId"))));
}

The User is returned in the JSON response.

Patch a User

Do a partial edit of an existing User with the following cURL and Java commands. Note, replace 1234 with your User’s ID.

User_PATCH_ById.sh

Command:

./User_PATCH_ById.sh 1234

Code:

curl \
	-H "Content-Type: application/json" \
	-X PATCH \
	"http://localhost:8080/o/headless-admin-user/v1.0/user-accounts/${1}" \
	-d "{\"familyName\": \"Bar\"}" \
	-u "[email protected]:learn"

User_PATCH_ById.java

Command:

java -classpath .:* -DuserId=1234 User_PATCH_ById

Code:

public static void main(String[] args) throws Exception {
	UserAccountResource.Builder builder = UserAccountResource.builder();

	UserAccountResource userAccountResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	UserAccount userAccount = userAccountResource.patchUserAccount(
		Long.valueOf(System.getProperty("userId")),
		new UserAccount() {
			{
				familyName = "Bar";
			}
		});

	System.out.println(userAccount);
}

Note that in the example Able and Baker’s last name has now changed from Foo to Bar.

Put a User

Do a complete overwrite of an existing User with the following cURL and Java commands. Note, replace 1234 with your User’s ID.

User_PUT_ById.sh

Command:

./User_PUT_ById.sh 1234

Code:

curl \
	-H "Content-Type: application/json" \
	-X PUT \
	"http://localhost:8080/o/headless-admin-user/v1.0/user-accounts/${1}" \
	-d "{\"alternateName\": \"Able\", \"emailAddress\": \"[email protected]\", \"familyName\": \"Goo\", \"givenName\": \"Able\"}" \
	-u "[email protected]:learn"

User_PUT_ById.java

Command:

java -classpath .:* -DuserId=1234 User_PUT_ById

Code:

public static void main(String[] args) throws Exception {
	UserAccountResource.Builder builder = UserAccountResource.builder();

	UserAccountResource userAccountResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	UserAccount userAccount = userAccountResource.putUserAccount(
		Long.valueOf(System.getProperty("userId")),
		new UserAccount() {
			{
				alternateName = "Baker";
				emailAddress = "[email protected]";
				familyName = "Goo";
				givenName = "Baker";
			}
		});

	System.out.println(userAccount);
}

Note that in the example the previous data has now been replaced with Able Goo and Baker Goo.

The previous user data has been replaced with the Patch service.

Delete a User

Delete an existing User with the following cURL and Java commands. Note, replace 1234 with your User’s ID.

User_DELETE_ById.sh

Command:

./User_DELETE_ById.sh 1234

Code:

curl \
	-X DELETE \
	"http://localhost:8080/o/headless-admin-user/v1.0/user-accounts/${1}" \
	-u "[email protected]:learn"

User_DELETE_ById.java

Command:

java -classpath .:* -DuserId=1234 User_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	UserAccountResource.Builder builder = UserAccountResource.builder();

	UserAccountResource userAccountResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	userAccountResource.deleteUserAccount(
		Long.valueOf(System.getProperty("userId")));
}

The Users Able Goo and Baker Goo have now been deleted.

Check out the API Explorer to see the list of all User related REST services.

Not finding what you're looking for?

Pardon our dust as we revamp and transition our product documentation to this site. If something seems missing, please check Liferay Help Center documentation for Liferay DXP 7.2 and previous versions.

Try Liferay's Help Center