Overview

Universal Controller supports the following RESTful-based web services for Credential operations, which are listed alphabetically on this page.

Create a Credential
Delete a Credential
List Credentials
Modify a Credential
Read a Credential

Formatting specifications for each web service, including details about property requirements, are provided.

Create a Credential

	Description
URI	http://host_name/uc/resources/credential
HTTP Method	POST
Description	Creates a Credential.
Example URI	http://localhost:8080/uc/resources/credential
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Create a Credential: Example Request, below.
Properties	See Credential Properties.
Example Response	Status 200 /OK Successfully created the credential with sysId {sysId}. Status 400 /Bad Request Create credential failed. A duplicate value has been detected. Name must be unique.

Create a Credential: Example Request

XML Request

JSON Request

XML Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
    <description />
    <name>AWS_Secrets_Manager</name>
    <opswiseGroups/>
    <provider>AWS Secrets Manager</provider>
    <providerParameters>
        <providerParameter>
            <name>ACCESS_KEY_ID</name>
            <value>*****</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ACCESS_KEY</name>
            <value>*****</value>
        </providerParameter>
        <providerParameter>
            <name>REGION</name>
            <value>us-east-1</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ID</name>
            <value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSWORD_KEY</name>
            <value>password</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSPHRASE_KEY</name>
            <value></value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_TOKEN_KEY</name>
            <value></value>
        </providerParameter>
    </providerParameters>
    <runtimeKeyLocation />
    <runtimeUser>secret</runtimeUser>
    <sysId>f71d4960469840c2ac3734962405bedd</sysId>
    <type>Standard</type>
</credential>

JSON Request

{
    "description": null,
    "exportReleaseLevel": "7.3.0.0",
    "exportTable": "ops_credentials",
    "name": "AWS_Secrets_Manager",
    "opswiseGroups": [],
    "provider": "AWS Secrets Manager",
    "providerParameters": [
        {
            "name": "ACCESS_KEY_ID",
            "value": "*****"
        },
        {
            "name": "SECRET_ACCESS_KEY",
            "value": "*****"
        },
        {
            "name": "REGION",
            "value": "us-east-1"
        },
        {
            "name": "SECRET_ID",
            "value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
        },
        {
            "name": "SECRET_PASSWORD_KEY",
            "value": "password"
        },
        {
            "name": "SECRET_PASSPHRASE_KEY",
            "value": ""
        },
        {
            "name": "SECRET_TOKEN_KEY",
            "value": ""
        }
    ],
    "retainSysIds": true,
    "runtimeKeyLocation": null,
    "runtimeUser": "secret",
    "sysId": "f71d4960469840c2ac3734962405bedd",
    "type": "Standard",
    "version": 28
}

Credential Properties

Properties	UI Field Name	Description	Specifications	Required
`description`	Description	User-defined; description of this record.		N
`exportReleaseLevel`	n/a	Universal Controller release that the record was exported from.	read only	N
`exportTable`	n/a	Record table information.	read only	N
`name`	Name	Name used within the Controller to identify this Credential.	Maximum 40 alphanumerics.	Y
`opswiseGroups`	Member of Business Services	Business Services that this record belongs to. Format: XML <opswiseGroups> <opswiseGroup>group1</opswiseGroup> <opswiseGroup>group2</opswiseGroup> </opswiseGroups> JSON "opswiseGroups": ["group1","group2"]		N
`provider`	Provider	Provider of credentials.	Valid values (case-insensitive): As String = Universal Controller, As Value = 1 As String = AWS Secrets Manager, As Value=2 As String = Azure Key Vault, As Value = 3 As String = CyberArk Credential Provider, As Value = 4 As String = CyberArk Central Credential Provider, As Value = 5 Default is Universal Controller (1).	N
`providerParameters`	Provider Parameters	Set of parameters specific to provider. See Provider Parameters for provider parameter details for each provider.	XML <providerParameters> <providerParameter> <name>PARAMETER_1</name> <value>VALUE_1</value> </providerParameter> <providerParameter> <name>PARAMETER_2</name> <value>VALUE_2</value> </providerParameter> </providerParameters> JSON "providerParameters": [ { "name": "PARAMETER_1", "value": "VALUE_1" }, { "name": "PARAMETER_2", "value": "VALUE_2" } ]	Y (if provider is not Universal Controller)
`retainSysIds`	n/a	Specification for whether or not the Create a Credential web service will persist the sysId property. If retainSysIds="true" and `sysId` is included in the request, `sysId` will be persisted to the database. If retainSysIds="false" and `sysId` is included in the request, `sysId` will be ignored; it will be autogenerated by the Controller. Note In XML web services, `retainSysIds` is specified as an attribute in the <credential> element.	Optional; Valid values: true/false (default is true).	N
`runtimeKeyLocation`	Key Location (SFTP only)	Using SFTP requires that you supply a valid credential that specifies the location of the SSL/TLS Private key on your Agent. This property provides the location, which must exist on the Agent where you intend to run the SFTP task. Currently, the Controller does not support password authentication for SFTP Transfer. For File Transfer over SSL/TLS, make sure you have your private/public keys properly set up and working before you configure the Controller to use it. For example, to validate the keys, log into your destination server from your agent server using SSL/TLS.		N
`runtimePassPhrase`	Pass Phrase (SFTP only)	Pass phrase for the Runtime User's SSL/TLS Private key file.		N
`runtimePassword`	Runtime Password	Runtime user's password.	If `runtimePassword` is omitted in the request, it will be ignored. If `runtimePassword` is provided in the request, it will be updated.	N
`runtimeToken`	Token	Runtime user Token that can be used with the ${_credentialToken(credential_name)} function.	If `runtimeToken` is omitted in the request, it will be ignored. If `runtimeToken` is provided in the request, it will be updated.	N
`runtimeUser`	Runtime User	Runtime user ID, including an LDAP- or AD-formatted user ID, under which the job will be run.		Y
`sysId`	n/a	System ID field in the database for this Credential record.	Persisted only if retainSysIds is set to true.	N
`type`	Type	Type of Credential. Note: You cannot modify the type after the Credential has been created, but you can convert any Credential type to any other type.	Valid Values: As String = Standard, As Value = 1 As String = Resolvable, As Value = 2 As String = Web Service, As Value = 3 As String = Email, As Value = 4 Default is Standard (1).	N

Provider Parameters

If a provider parameter is secure, its value will not be exposed in the GET response (xml: no <value> property; json: "value": null). However, you can manually add it to the PUT/POST request to update the value.

AWS Secrets Manager

Provider Parameter	Required	Description
ACCESS_KEY_ID	true	The AWS access key, used to identify the user interacting with AWS.
SECRET_ACCESS_KEY	true	The AWS secret access key, used to authenticate the user interacting with AWS.
REGION	true	The region name (e.g., us-east-1).
SECRET_ID	true	The ARN or name of the secret to retrieve.
SECRET_PASSWORD_KEY	false	If this secret was created by using the console, then Secrets Manager stores the information as a JSON structure of key/value pairs. Specifies the key for the password in the JSON structure. If left unspecified, the password will evaluate to the entire secret value.
SECRET_PASSPHRASE_KEY	false	Specifies the key for the passphrase in the JSON structure. If left unspecified, the passphrase will be undefined.
SECRET_TOKEN_KEY	false	Specifies the key for the token in the JSON structure. If left unspecified, the token will be undefined.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 3600 seconds / 1 hour)

Azure Key Vault

Provider Parameter	Required	Description
KEY_VAULT_NAME	true	The name of the Key Vault used to build the vault URL to send HTTP requests to. https://<your-key-vault-name>.vault.azure.net
SECRET_NAME	true	The name of the secret.
CLIENT_ID	true	The client (application) ID.
TENANT_ID	true	The Azure Active Directory tenant (directory) Id.
CLIENT_SECRET		The client secret used to authenticate. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
CLIENT_ASSERTION		The client assertion used to authenticate. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
PEM_CERTIFICATE		The path of the PEM certificate used for authenticating. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
PFX_CERTIFICATE		The path of the PFX certificate used for authenticating. Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.
PFX_CERTIFICATE_PASSWORD		The password for the PFX certificate. Required if the PFX_CERTIFICATE is specified.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 28800 seconds / 8 hours)

CyberArk Credential Provider

Provider Parameter	Required	Description
APPLICATION_ID	true	The unique ID of the application issuing the password request.
SAFE	true	The name of the Safe where the password is stored.
FOLDER	true	The name of the folder where the password is stored.
OBJECT	true	The name of the password object to retrieve.
REASON	false	The reason for retrieving the password.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 5

CyberArk Central Credential Provider

Provider Parameter	Required	Description
HOST	true	The hostname of the Central Credential Provider.
PORT	true	The port of the Central Credential Provider.
APPLICATION_ID	true	The unique ID of the application issuing the password request.
SAFE	true	The name of the Safe where the password is stored.
FOLDER	true	The name of the folder where the password is stored.
OBJECT	true	The name of the password object to retrieve.
CACHE_TTL	false	The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 5 seconds)

Delete a Credential

	Description
URI	http://host_name/uc/resources/credential
HTTP Method	DELETE
Description	Deletes a Credential.
URI Parameters	See Delete a Credential: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/credential?credentialname=test
Example Response	Status 200 /OK Credential deleted successfully. Status 400 /Bad Request Mutual exclusion violation. Cannot specify `credentialname` and `credentialid` at the same time. Status 404 /Not Found A credential with {name/id} "test" does not exist.

Delete a Credential: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`credentialid`	ID used within the Controller to identify this Credential.	String; URI parameter.	Y (unless `credentialname` is specified)	`credentialname`
`credentialname`	Name used within the Controller to identify this Credential.	String; URI parameter.	Y (unless `credentialid` is specified)	`credentialid`

List Credentials

	Description
URI	http://host_name/uc/resources/credential/list
HTTP Method	GET
Description	Retrieves information on all Credentials.
Example URI	http://localhost:8080/uc/resources/credential/list
Authentication	HTTP Basic
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example Response	See List Credentials: Example Response, below.
Properties	See Credential Properties.

List Credentials: Example Response

XML Response

JSON Response

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
    <description />
    <name>AWS_Secrets_Manager</name>
    <opswiseGroups/>
    <provider>AWS Secrets Manager</provider>
    <providerParameters>
        <providerParameter>
            <name>ACCESS_KEY_ID</name>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ACCESS_KEY</name>
        </providerParameter>
        <providerParameter>
            <name>REGION</name>
            <value>us-east-1</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ID</name>
            <value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSWORD_KEY</name>
            <value>password</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSPHRASE_KEY</name>
            <value></value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_TOKEN_KEY</name>
            <value></value>
        </providerParameter>
    </providerParameters>
    <runtimeKeyLocation />
    <runtimeUser>secret</runtimeUser>
    <sysId>f71d4960469840c2ac3734962405bedd</sysId>
    <type>Standard</type>
</credential>

JSON Response

{
    "description": null,
    "exportReleaseLevel": "7.3.0.0",
    "exportTable": "ops_credentials",
    "name": "AWS_Secrets_Manager",
    "opswiseGroups": [],
    "provider": "AWS Secrets Manager",
    "providerParameters": [
        {
            "name": "ACCESS_KEY_ID",
            "value": null
        },
        {
            "name": "SECRET_ACCESS_KEY",
            "value": null
        },
        {
            "name": "REGION",
            "value": "us-east-1"
        },
        {
            "name": "SECRET_ID",
            "value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
        },
        {
            "name": "SECRET_PASSWORD_KEY",
            "value": "password"
        },
        {
            "name": "SECRET_PASSPHRASE_KEY",
            "value": ""
        },
        {
            "name": "SECRET_TOKEN_KEY",
            "value": ""
        }
    ],
    "retainSysIds": true,
    "runtimeKeyLocation": null,
    "runtimeUser": "secret",
    "sysId": "f71d4960469840c2ac3734962405bedd",
    "type": "Standard",
    "version": 28
}

Modify a Credential

	Description
URI	http://host_name/uc/resources/credential
HTTP Method	PUT
Description	Modifies the Credential specified by the `sysId`.
Example URI	http://localhost:8080/uc/resources/credential
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Modify a Credential: Example Request, below.
Properties	See Credential Properties.
Example Response	Status 200 /OK Successfully updated the credential with sysId <sysId> to version <version>.

Modify a Credential: Example Request

XML Request

JSON Request

XML Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
    <description />
    <name>AWS_Secrets_Manager</name>
    <opswiseGroups/>
    <provider>AWS Secrets Manager</provider>
    <providerParameters>
        <providerParameter>
            <name>ACCESS_KEY_ID</name>
            <value>*****</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ACCESS_KEY</name>
            <value>*****</value>
        </providerParameter>
        <providerParameter>
            <name>REGION</name>
            <value>us-east-1</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ID</name>
            <value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSWORD_KEY</name>
            <value>password</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSPHRASE_KEY</name>
            <value></value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_TOKEN_KEY</name>
            <value></value>
        </providerParameter>
    </providerParameters>
    <runtimeKeyLocation />
    <runtimeUser>secret</runtimeUser>
    <sysId>f71d4960469840c2ac3734962405bedd</sysId>
    <type>Standard</type>
</credential>

JSON Request

{
    "description": null,
    "exportReleaseLevel": "7.3.0.0",
    "exportTable": "ops_credentials",
    "name": "AWS_Secrets_Manager",
    "opswiseGroups": [],
    "provider": "AWS Secrets Manager",
    "providerParameters": [
        {
            "name": "ACCESS_KEY_ID",
            "value": "*****"
        },
        {
            "name": "SECRET_ACCESS_KEY",
            "value": "*****"
        },
        {
            "name": "REGION",
            "value": "us-east-1"
        },
        {
            "name": "SECRET_ID",
            "value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
        },
        {
            "name": "SECRET_PASSWORD_KEY",
            "value": "password"
        },
        {
            "name": "SECRET_PASSPHRASE_KEY",
            "value": ""
        },
        {
            "name": "SECRET_TOKEN_KEY",
            "value": ""
        }
    ],
    "retainSysIds": true,
    "runtimeKeyLocation": null,
    "runtimeUser": "secret",
    "sysId": "f71d4960469840c2ac3734962405bedd",
    "type": "Standard",
    "version": 28
}

Read a Credential

URI	http://host_name/uc/resources/credential
HTTP Method	GET
Description	Retrieves information on a specific Credential.
URI Parameters	See Read a Credential: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/credential?credentialname=test http://localhost:8080/uc/resources/credential?credentialid=f87848b00a0001037f43e7c81c8ec969
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example Response	See Read a Credential: Example Response, below.
Properties	See Credential Properties.

Read a Credential: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`credentialid`	ID used within the Controller to identify this Credential.	String; URI parameter.	Y (unless `credentialname` is specified)	`credentialname`
`credentialname`	Name used within the Controller to identify this Credential.	String; URI parameter.	Y (unless `credentialid` is specified)	`credentialid`

Read a Credential: Example Response

XML Response

JSON Response

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
    <description />
    <name>AWS_Secrets_Manager</name>
    <opswiseGroups/>
    <provider>AWS Secrets Manager</provider>
    <providerParameters>
        <providerParameter>
            <name>ACCESS_KEY_ID</name>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ACCESS_KEY</name>
        </providerParameter>
        <providerParameter>
            <name>REGION</name>
            <value>us-east-1</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_ID</name>
            <value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSWORD_KEY</name>
            <value>password</value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_PASSPHRASE_KEY</name>
            <value></value>
        </providerParameter>
        <providerParameter>
            <name>SECRET_TOKEN_KEY</name>
            <value></value>
        </providerParameter>
    </providerParameters>
    <runtimeKeyLocation />
    <runtimeUser>secret</runtimeUser>
    <sysId>f71d4960469840c2ac3734962405bedd</sysId>
    <type>Standard</type>
</credential>

JSON Response

{
    "description": null,
    "exportReleaseLevel": "7.3.0.0",
    "exportTable": "ops_credentials",
    "name": "AWS_Secrets_Manager",
    "opswiseGroups": [],
    "provider": "AWS Secrets Manager",
    "providerParameters": [
        {
            "name": "ACCESS_KEY_ID",
            "value": null
        },
        {
            "name": "SECRET_ACCESS_KEY",
            "value": null
        },
        {
            "name": "REGION",
            "value": "us-east-1"
        },
        {
            "name": "SECRET_ID",
            "value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
        },
        {
            "name": "SECRET_PASSWORD_KEY",
            "value": "password"
        },
        {
            "name": "SECRET_PASSPHRASE_KEY",
            "value": ""
        },
        {
            "name": "SECRET_TOKEN_KEY",
            "value": ""
        }
    ],
    "retainSysIds": true,
    "runtimeKeyLocation": null,
    "runtimeUser": "secret",
    "sysId": "f71d4960469840c2ac3734962405bedd",
    "type": "Standard",
    "version": 28
}

Test Provider

	Description
URI	http://host_name/uc/resources/credential/testprovider
HTTP Method	POST
Description	Run the Test Provider command for the specified credentials.
Example URI	http://localhost:8080/uc/resources/credential/testprovider?credentialname=My_AWS_Secret
Authentication	HTTP Basic
Produces Content-Type	application/xml, application/json
Consumes Content-Type	N/A
Example Responses	Status 200 Successfully created the credentialname with id {uuid}. Status 400 Error message. Status 403 Operation prohibited due to security constraints. Status 404 A credential with name “{name}” does not exist. A credential with id "{uuid}" does not exist. Status 500 Unexpected request failure. See log(s) for more details.

Test Provider: Query Parameters

The following request parameters will be needed for the service.

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

credentialname

N/A

Name used within the Controller to identify the Credentials.

String; URI parameter

Y (unless credentialid is specified)

credentialid

N/A

ID used within the Controller to identify the Credentials.

String; URI parameter

Y (unless credentialname is specified)

credentialname

Test Provider: Example Response

XML Response

JSON Response

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<command-response>
    <type>credential_provider_test</type>
    <success>true</success>
    <info>Credential provider test completed successfully for "My_AWS_Secret".</info>
    <errors></errors>
</command-response>

XML Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<command-response>
    <type>credential_provider_test</type>
    <success>false</success>
    <info></info>
    <errors>The security token included in the request is invalid.</errors>
</command-response>

JSON Response

{
    "type": "credential_provider_test",
    "success": true,
    "info": "Credential provider test completed successfully for \"My_AWS_Secret\".",
    "errors": ""
}

JSON Response

{
    "type": "credential_provider_test",
    "success": false,
    "info": "",
    "errors": "The security token included in the request is invalid."
}

Universal Controller 7.4.x

Credential Web Services

Overview

Create a Credential

Create a Credential: Example Request

Credential Properties

Provider Parameters

AWS Secrets Manager

Azure Key Vault

CyberArk Credential Provider

CyberArk Central Credential Provider

Delete a Credential

Delete a Credential: URI Parameters

List Credentials

List Credentials: Example Response

Modify a Credential

Modify a Credential: Example Request

Read a Credential

Read a Credential: URI Parameters

Read a Credential: Example Response

Test Provider

Test Provider: Query Parameters

Test Provider: Example Response