Create and manage Cloud Directory users

This topic describes how to create, modify, and delete users in the CyberArk Identity Cloud Directory, using the CyberArk Identity API.

Overview

CyberArk Identity provides a built-in user service, CyberArk Identity Cloud Directory, which you can use to store users for your application. The Cloud User Management API provides calls to create, modify, and delete users, as well as retrieve information about current users, for Cloud Directory. The Identity Service also provides a set of generic user functions that apply to all users, both Cloud Directory users and users from other sources, such as Active Directory or social login. For example, to retrieve a user's picture, reset a user's password, set a user's security question, or send an invite to a user, among other things, see Perform generic user functions.

To create, modify, or delete users you must be a system administrator or have user-management permissions.

When you create a user, in addition to required and optional account and profile information, you can specify:

That the account is locked; for example, if you want to create accounts that won't be used until a later date and require an administrator to unlock.
Whether the password must be reset when the user first logs in.
Whether to add the user to Everybody, which is a built-in role that allows an administrator to apply default characteristics—such as access to a set of common applications—to everyone in the organization. The Everybody role is read-only; you cannot add users to this role later on with the Role API, but must do so now when creating a user.
Whether to add the user to the System Administrator role.
Whether to send an invite to the new user.

If you connect your CyberArk Identity tenant to an external store (Active Directory or LDAP), its users are able to authenticate to the cloud service using their Active Directory or LDAP account. You don't need to replicate these accounts in CyberArk Identity but simply reference them when authenticating a user. See Perform generic user functions.

Get a list of current users

Before adding a new user, you can determine whether the user already exists by calling /Redrock/Query against the User Table to return a list of current users.

/Redrock/query
{
	"Script":"Select Username, ID from User ORDER BY Username COLLATE NOCASE"
}

The query returns the ID and name for all users similar to the one shown here:

{
	"success": true,
	"Result": 
	{
		"IsAggregate": false,
		"Count": 44,
		"Columns": [
			{
				"Name": "ID",
				"IsHidden": false,
				"DDName": "ID",
				"Title": "ID",
				"DDTitle": "ID",
				"Description": "Row Identifier (primary key)",
				"Type": 12,
				"Format": null,
				"Width": 0,
				"TableKey": "Primary",
				"ForeignKey": null
			},
			{
				"Name": "Username",
				"IsHidden": false,
				"DDName": "Username",
				"Title": "Username",
				"DDTitle": "Username",
				"Description": "User name.",
				"Type": 12,
				"Format": null,
				"Width": 0,
				"TableKey": "Alternate",
				"ForeignKey": null
			}
		],
		"FullCount": 44,
		"Results": [
			{
				"Entities": [
					{
						"Type": "User",
						"Key": "e7ed3e73-d115-44f3-9553-4bcc1a4ecc05",
						"IsForeignKey": false
					}
				],
				"Row": {
					"ID": "e7ed3e73-d115-44f3-9553-4bcc1a4ecc05",
					"Username": "auser1@qa.com"
					}
				},
				{
					"Entities": [
						{
							"Type": "User",
							"Key": "1ee22405-59b8-49a9-b64b-5b13aee592ce",
							"IsForeignKey": false
						}
					],
					"Row": {
						"ID": "1ee22405-59b8-49a9-b64b-5b13aee592ce",
						"Username": "admin@abc1234"
					}
				},
           
			...
        
			{
				"Entities": [
					{
						"Type": "User",
						"Key": "0ee88549-7c48-486d-a9f5-63cf9167890a",
						"IsForeignKey": false
					}
				],
				"Row": {
					"ID": "0ee88549-7c48-486d-a9f5-63cf9167890a",
					"Username": "test2@ddog.com"
					}
				{
					"Entities": [
						{
							"Type": "User",
							"Key": "d9fed598-7f16-4305-aaa8-97a9f5c12c00",
							"IsForeignKey": false
						}
					],
					"Row": {
						"ID": "d9fed598-7f16-4305-aaa8-97a9f5c12c00",
						"Username": "user1@ddog.com"
					}
				}
			],
			"ReturnID": ""
		},
		"Message": null, "MessageID": null, "Exception": null, "ErrorID": null, "ErrorCode": null, "InnerExceptions": null
}

Sign up a user

Call /CDirectoryService/Signup to sign up a user.

Below is a sample request for the API call. See the reference section for details about all the supported parameters.

/CDirectoryService/Signup
{
	"Name": "test3@doccraft",
	"DisplayName": "Test User",
	"Mail": mike11@somemail.com,
	"Password": "abcD1234",
	"MobileNumber": "+1-987-654-3210"
}

A successful call to Signup returns a UserId of the type UUID for the new user, as shown here:

{
	"success": true,
	"Result": {
		"UserId": "b943f157-04b7-4457-bc82-aea9e06fe839"
	},
	"Message": null, "MessageID": null, "Exception": null, "ErrorID": null, "ErrorCode": null,
	"IsSoftError": false, "InnerExceptions": null
}

You pass this UUID to any subsequent calls to manage the user.

This API is an early access API. It's possible that it may change in near future.

Create a user

Call /CDirectoryService/CreateUser to create a user.

Note the following about the parameters for this call:

Name requires a login suffix (doccraft in this example)
Password can be set to any arbitrary string because the user must reset it at the next login ("ForcePasswordChangeNext": true).
MobileNumber must be set in order to send an SMS invite ("SendSmsInvite": true).
Although InEverybodyRole is true by default, and InSysAdminRole is false by default, for clarity they are set explicitly to these values in the sample.

/CDirectoryService/CreateUser
{
	"Name": "test3@doccraft",
	"Mail": mike11@somemail.com,
	"Password": "abcD1234",
	"InEverybodyRole": true,
	"InSysAdminRole": false,
	"ForcePasswordChangeNext": true,
	"SendEmailInvite": true,
	"SendSmsInvite": true,
	"MobileNumber": "987-654-3210"
}

A successful call to CreateUser returns a UUID for the new user, as shown here:

{
"success":true,
"Result":"899103e2-2309-4f5d-bb27-9523c21846cc",
"Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
}

You pass this UUID to any subsequent calls to manage the user.

Update user information

Call /CDirectoryService/ChangeUser to modify a Cloud user account.

Pass the UUID of the user to update, and any fields that you want to update (if you omit ID, the function applies to the current user). For example, the following call updates the mobile number for the specified user:

/CDirectoryService/ChangeUser
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f",
"MobileNumber" "5105555555"
}

/CDirectoryService/ChangeUser changes the mobile number for the user account specified by the ID, and leaves all other fields with their current values.

Set user information

CyberArk Identity provides specific functions to set the picture for a Cloud Directory account, or to lock, disable, or set a Cloud Directory account to expired:

/CDirectoryService/SetUserPicture - Set the picture for a user.
/CDirectoryService/SetUserState - Set the state of a user to Locked, Disabled, or Expired.

For example, to lock an account (after too many failed logins), make a call such as the following:

/CDirectoryService/SetUserState
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f"
"state": "Locked"
}

You can reenable a locked account by setting the state to None; for example:

/CDirectoryService/SetUserState
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f"
"state": "None"
}

Delete a user

You can call /CDirectoryService/DeleteUser to delete a user from the cloud service. Specify either the name or UUID of the user to delete:

/CDirectoryService/DeleteUser
{
"ID": "5f766478-7008-4826-a08a-c6a0f8efb18f"
}