Manage applications for users

Users require access to a different set of application attributes from administrators. This topic describes how to do the following, using the CyberArk Identity API:

Retrieve all applications that are deployed for a user (by calling /UPRest/GetUPData).
Retrieve a specific application for a user (by calling /UPRest/GetAppByKey).
Set, update, or clear the user name and password for an application (by calling /UPRest/SetUserCredsForApp).
Create tags for an application (by calling /UPRest/UpsertTagsForApp).

Retrieve all applications for a user

The API provides a number of different calls to retrieve applications that have been deployed. For example, to retrieve all the applications deployed for a specific user, call /UPRest/GetUPData and pass the name of the user (username). Also specify whether to use the cache (force: false) or not (force: true):

/UPRest/GetUPData
	{
		'username': 'test3@doccraft',
		'force': 'true'
	}

This call returns complete information for all applications that have been deployed for the specified user. This sample shows a reduced set of information for a number of applications and complete information for the Ebay web application:

/UPRest/GetUPData sample response:

{
	"success": true,
	"Result": {
		"Apps": [
			{
				"Description": "Standard test password",
				"DisplayName": null,
				"TemplateName": "Generic Bookmark",
				"CpsType": "Account",
				"AdminTag": "Privilege Service",
				"CpsHostFQDN": "192.168.132.10",
				"_RowKey": "@!/3834d122-30cd-4893-8820-41af9447b313",
				...
			},
			{
				"Description": "Get Satisfaction is the leading customer engagement platform that helps companies build better relationships with their customers and prospects, through the best online customer community.",
				"DisplayName": "Get Satisfaction",
				"TemplateName": "GetSatisfaction",
				"AdminTag": "Customer Service",
				"AppTypeDisplayName": "Web - User Password",
				"_RowKey": "026be8d7-f9f6-4aaf-a66b-03277fc70490",
				...
			},
			...      
			{
				"Description": "AIM is the simplest (and most fun) way to chat and share with people and groups you care about. ",
				"DisplayName": "AIM",
				"TemplateName": "AIM",
			"AdminTag": "Communication",
			"AppTypeDisplayName": "Web - User Password",
			"_RowKey": "2451b1e9-59d6-4ed5-9ef2-8dbb5ee86eb6",
			...
			},
			{
				"Intranet": false,
				"PasswordIsSet": true,
				"UsernameField": "input#userid",
				"Name": "Ebay",
				"Category": "Other",
				"DisplayName": "Ebay",
				"Scheme": "HttpHttps",
				"AppTypeDisplayName": "Web - User Password",
				"CbeMinVersion": "1.102.1309",
				"Automatic": true,
				"AdminTag": "Other",
				"Description": "Buy and sell electronics, cars, fashion apparel, collectibles, sporting goods, digital cameras, baby items, coupons, and everything else on eBay, the world's online marketplace",
				"FormAction": "https://signin.ebay.com/ws/eBayISAPI.dll?co_partnerId=2&siteid=0&UsingSSL=1",
				"SubmitField": "input#sgnBt",
				"AppType": "Web",
				"Shortcut": false,
				"Username": test3@doccraft,
				"Url": "https://signin.ebay.com/ws/eBayISAPI.dll?SellItem",
				"Icon": "/vfslow/lib/application/icons/ebay",
				"FormField": "form#SignInForm",
				"WebAppTypeDisplayName": "User Password",
				"PasswordField": "input#pass",
				"_RowKey": "487e4925-ba49-4a40-a5de-fe07cb4cee2a",
				"AppKey": "487e4925-ba49-4a40-a5de-fe07cb4cee2a",
				"WebAppType": "UsernamePassword",
				"Rank": 1,
				"TemplateName": "Ebay",
				"WebUPAppType": "BrowserExtension",
				"UsernameRO": false,
				"HostNameSuffix": "ebay.com"
			},
		...

The UUID in the AppKey field uniquely identifies a specific web application. You can save the UUIDs to pass to other functions that manage user access to applications, as shown in the following sections. The /UPRest (User-Portal) functions are designed to retrieve information for regular users, not administrators. Most /UPRest calls do not provide a parameter to identify the user, but rather assume that the call applies to the currently authenticated user. For example, when you call /UPRest/GetAppByKey, /UPRest/SetUserCredsForApp, and so on, you pass the app key to identify the app, and CyberArk Identity applies the function to the app for the currently authenticated user.

Retrieve a specific application for a user

Call /UPRest/GetAppByKey to retrieve a specific application for the current user. For example, pass the UUID saved from the previous call to /UPRest/GetUPData to retrieve the eBay application:

/UPRest/GetAppByKey
	{
		'appkey': '487e4925-ba49-4a40-a5de-fe07cb4cee2a'
	}

Ebay app data:

{
	"success": true,
	"Result": {
		"Description": "Buy and sell electronics, cars, fashion apparel, collectibles, sporting goods, digital cameras, baby items, coupons, and everything else on eBay, the world's online marketplace",
		"UsernameField": "input#userid",
		"HostNameSuffix": "ebay.com",
		"DisplayName": "Ebay",
		"TemplateName": "Ebay",
		"AdminTag": "Other",
		"PasswordField": "input#pass",
		"Scheme": "HttpHttps",
		"AppTypeDisplayName": "Web - User Password",
		"_RowKey": "487e4925-ba49-4a40-a5de-fe07cb4cee2a",
		"SubmitField": "input#sgnBt",
		"UsernameRO": false,
		"PasswordIsSet": true,
		"FormField": "form#SignInForm",
		"Category": "Other",
		"Icon": "/vfslow/lib/application/icons/ebay",
		"WebUPAppType": "BrowserExtension",
		"Intranet": false,
		"CbeMinVersion": "1.102.1309",
		"Username": test3@doccraft,
		"Shortcut": false,
		"Name": "Ebay",
		"AppType": "Web",
		"Rank": 1,
		"WebAppTypeDisplayName": "User Password",
		"WebAppType": "UsernamePassword",
		"AppKey": "487e4925-ba49-4a40-a5de-fe07cb4cee2a",
		"Url": "https://signin.ebay.com/ws/eBayISAPI.dll?SellItem",
		"FormAction": "https://signin.ebay.com/ws/eBayISAPI.dll?co_partnerId=2&siteid=0&UsingSSL=1"
	},
	"Message":null,  "MessageID":null, "Exception":null, "ErrorID":null, "ErrorCode":null, "InnerExceptions":null
}

Set user credentials for an application

Call /UPRest/SetUserCredsForApp to set user credentials for an application that requires a user name and password. When a user subsequently launches the application, no user name or password is required. Pass the app key and a user name and password provided by the user; for example: This call sets credentials for the currently authenticated user. It returns null for Result.

/UPRest/SetUserCredsForApp
{
	'appkey': '487e4925-ba49-4a40-a5de-fe07cb4cee2a'
	'Username': 'mnice@acme.com',
	'Password': 'ABcd1230'
}

You can clear credentials for an application by calling /UPRest/SetUserCredsForApp and passing null for username and password; for example:

/UPRest/SetUserCredsForApp
   
{
	'appkey': '487e4925-ba49-4a40-a5de-fe07cb4cee2a'
	'Username': '',
	'Password': ''
}

Create user tags for an application

Tags allow users to organize applications by type. Before adding tags to an application, you can call /UPRest/GetTagsForApp and pass the app key to see which tags, if any, already apply to an application; for example:

/UPRest/GetTagsForApp
{
	"appkey": "487e4925-ba49-4a40-a5de-fe07cb4cee2a"
}

You call /UPRest/UpsertTagsForApp to tag an application. Pass the ID of the application and one or more tag names; for example:

/UPRest/UpsertTagsForApp
{
	"appkey": "487e4925-ba49-4a40-a5de-fe07cb4cee2a", 
	"tagnames": 
		[
			"Shopping",
			"E-Commerce",
			"Personal"
		]
}

The call attaches three tags ("Shopping", "E-Commerce", and "Personal") to the application.