Account Users and Roles APIs¶

You can manage Account Users and Account Roles from the Applications menu, but you can also use Liferay’s REST APIs. Call these services to create and manage Account Users and Roles.

Adding an Account User¶

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u29

Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip Accounts API Basics.

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

unzip liferay-t5p9.zip

Use the Accounts_GET_FromInstance resource to get a list of account IDs. Make note of the account ID you wish to add a user for.

Use the cURL script to add a new account user to the account. On the command line, navigate to the curl folder. Execute the AccountUser_POST_ToAccount.sh script with the account ID as a parameter.

./AccountUser_POST_ToAccount.sh 1234

The JSON response shows a new account has been added:

     {
     "accountBriefs" : [ {
         "id" : 38935,
         "name" : "Able",
         "roleBriefs" : [ ]
     } ],
     "additionalName" : "",
     "alternateName" : "dog",
     "birthDate" : "1977-01-01T00:00:00Z",
     "customFields" : [ ],
     "dashboardURL" : "",
     "dateCreated" : "2021-10-12T21:00:59Z",
     "dateModified" : "2021-10-12T21:01:01Z",
     "emailAddress" : "[email protected]",
     "externalReferenceCode" : "",
     "familyName" : "Easy",
     "givenName" : "Dog",
     "id" : 39005,
     "jobTitle" : "",
     "keywords" : [ ],
     "name" : "Dog Easy",
     "organizationBriefs" : [ ],
     "profileURL" : "",
     "roleBriefs" : [ {
         "id" : 20111,
         "name" : "User"
     } ],
     "siteBriefs" : [ {
         "id" : 20125,
         "name" : "Global"
     }, {
         "id" : 20123,
         "name" : "Guest"
     } ],
     "userAccountContactInformation" : {
         "emailAddresses" : [ ],
         "facebook" : "",
         "jabber" : "",
         "postalAddresses" : [ ],
         "skype" : "",
         "sms" : "",
         "telephones" : [ ],
         "twitter" : "",
         "webUrls" : [ ]
     }
     }     

Navigate to Global Menu → Applications → Accounts. Click the account you created a User for. Click the Users tab and see the new User that was created.

See that a new account user has been added.

The REST service can also be called using the Java client. Navigate out of the curl folder and into the java folder. Compile the source files with the following command:
```
javac -classpath .:* *.java
```
Run the AccountUser_POST_ToAccount.java class with the following command. Replace 1234 with the account’s ID.
```
java -classpath .:* -DaccountId=1234 AccountUser_POST_ToAccount
```

Examine the cURL Command¶

The AccountUser_POST_ToAccount.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/accounts/${1}/user-accounts" \
	-d "{\"alternateName\": \"Dog\", \"emailAddress\": \"[email protected]\", \"familyName\": \"Easy\", \"givenName\": \"Dog\"}" \
	-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/accounts/${1}/user-accounts"`	The REST service endpoint
`-d "{\"alternateName\": \"Dog\", \"emailAddress\": \"dog@liferay.com\", \"familyName\": \"Easy\", \"givenName\": \"Dog\"}"`	The data you are requesting to post
`-u "test@liferay.com:learn"`	Basic authentication credentials

Note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class¶

The Account_POST_ToInstance.java class adds an Account User by calling the related service.

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

	AccountResource accountResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	Account account = accountResource.postAccount(
		new Account() {
			{
				description = "Foo";
				name = "Fox";
			}
		});

	System.out.println(account);
}

This class invokes the REST service using 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 `UserAccountResource` service instance.
`UserAccount userAccount = userAccountResource.postAccountUserAccount(...);`	Calls the `userAccountResource.postAccountUserAccount` 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 methods.

Important

See AccountResource for service details.

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

Get Account Users from Account¶

You can list an account’s users by executing the following cURL or Java command. As above, replace 1234 with your account’s ID.

AccountUsers_GET_FromAccount.sh¶

Command:

./AccountUsers_GET_FromAccount 1234

Code:

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

AccountUsers_GET_FromAccount.java¶

Command:

java -classpath .:* -DaccountId=1234 AccountUsers_GET_FromAccount

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.getAccountUserAccountsPage(
		Long.valueOf(System.getProperty("accountId")), null, null,
		Pagination.of(1, 2), null);

	System.out.println(page);
}

The Account’s UserAccount objects appear in JSON.

Post an Account Role¶

Create a new Account Role for a specific account. Note, replace 1234 with your account’s ID.

AccountRole_POST_ToAccount.sh¶

Command:

./AccountRole_POST_ToAccount.sh 1234

Code:

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

AccountRole_POST_ToAccount.java¶

Command:

java -classpath .:* -DaccountId=1234 AccountRole_POST_ToAccount

Code:

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

	AccountRoleResource accountRoleResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	AccountRole accountRole = accountRoleResource.postAccountAccountRole(
		Long.valueOf(System.getProperty("accountId")),
		new AccountRole() {
			{
				name = "How";
			}
		});

	System.out.println(accountRole);
}

Associate a User to an Account Role¶

You can associate a User with a specific Account Role. Replace 1234 with your Account’s ID. Replace 5678 with your Account Role’s ID. Replace 9012 with your Account User’s ID.

AccountRole_POST_UserAssociation.sh¶

Command:

./AccountRole_POST_UserAssociation.sh 1234 5678 9012

Code:

curl \
	-H "Content-Type: application/json" \
	-X POST \
	"http://localhost:8080/o/headless-admin-user/v1.0/accounts/${1}/account-roles/${2}/user-accounts/${3}" \
	-u "[email protected]:learn"

AccountRole_POST_UserAssociation.java¶

Command:

java -classpath .:* -DaccountId=1234 -DaccountRoleId=5678 -DuserAccountId=9012 AccountRole_POST_UserAssociation

Code:

	AccountRoleResource.Builder builder = AccountRoleResource.builder();

	AccountRoleResource accountRoleResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	accountRoleResource.postAccountAccountRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("accountId")),
		Long.valueOf(System.getProperty("accountRoleId")),
		Long.valueOf(System.getProperty("userAccountId")));
}

Get Account Roles from an Account¶

You can list an Account’s Account Roles by executing the following cURL or Java command. Replace 1234 with your Account’s ID.

AccountRoles_GET_FromAccount.sh¶

Command:

./AccountRoles_GET_FromAccount.sh 1234

Code:

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

AccountRoles_GET_FromAccount.java¶

Command:

java -classpath .:* -DaccountId=1234 AccountRoles_GET_FromAccount

Code:

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

	AccountRoleResource accountRoleResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	Page<AccountRole> page = accountRoleResource.getAccountAccountRolesPage(
		Long.valueOf(System.getProperty("accountId")), null,
		Pagination.of(1, 2), null);

	System.out.println(page);
}

The Account’s AccountRole objects appear in JSON.

Remove Account Role User Association¶

Remove an Account Role association from a specific Account User. Replace 1234 with your Account’s ID. Replace 5678 with your Account Role’s ID. Replace 9012 with your Account User’s ID.

AccountRole_DELETE_UserAssociation.sh¶

Command:

./AccountRole_DELETE_UserAssociation.sh 1234 5678 9012

Code:

curl \
	-H "Content-Type: application/json" \
	-X DELETE \
	"http://localhost:8080/o/headless-admin-user/v1.0/accounts/${1}/account-roles/${2}/user-accounts/${3}" \
	-u "[email protected]:learn"

AccountRole_DELETE_UserAssociation.java¶

Command

java -classpath .:* -DaccountId=1234 -DaccountRoleId=5678 -DuserAccountId=9012 AccountRole_DELETE_UserAssociation

Code:

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

	AccountRoleResource accountRoleResource = builder.authentication(
		"[email protected]", "learn"
	).build();

	accountRoleResource.deleteAccountAccountRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("accountId")),
		Long.valueOf(System.getProperty("accountRoleId")),
		Long.valueOf(System.getProperty("userAccountId")));
}

The API Explorer shows all of the Account services and schemas and has an interface to try out each service.

Documentation

Account Users and Roles APIs¶

Adding an Account User¶

Examine the cURL Command¶

Examine the Java Class¶

Get Account Users from Account¶

AccountUsers_GET_FromAccount.sh¶

AccountUsers_GET_FromAccount.java¶

Post an Account Role¶

AccountRole_POST_ToAccount.sh¶

AccountRole_POST_ToAccount.java¶

Associate a User to an Account Role¶

AccountRole_POST_UserAssociation.sh¶

AccountRole_POST_UserAssociation.java¶

Get Account Roles from an Account¶

AccountRoles_GET_FromAccount.sh¶

AccountRoles_GET_FromAccount.java¶

Remove Account Role User Association¶

AccountRole_DELETE_UserAssociation.sh¶

AccountRole_DELETE_UserAssociation.java¶

Not finding what you're looking for?