Credential Web Services

Owned by Former user (Deleted)
Last updated: Jan 25, 2023 by Stonebranch
4 min read

Overview

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

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
<credential retainSysIds="true">
    <description />
    <name>test</name>
    <opswiseGroups>
       <opswiseGroup>bs1</opswiseGroup>
       <opswiseGroup>bs2</opswiseGroup>
    </opswiseGroups>
    <runtimeKeyLocation />
    <runtimePassPhrase />
    <runtimePassword>test</runtimePassword>
    <runtimeToken>c89e7b2caf4247909bc46041df8a2643</runtimeToken>
    <runtimeUser>test</runtimeUser>
    <sysId>36208a27bda64312a854985314922953</sysId>
    <type>Standard</type> </credential>
 JSON Request
{
  "description": "Testing",
  "name": "test",
  "opswiseGroups": [
    "bs1",
    "bs2"
  ],
  "retainSysIds": true,
  "runtimeKeyLocation": null,
  "runtimePassPhrase": null,
  "runtimePassword": "test",
  "runtimeToken": "c89e7b2caf4247909bc46041df8a2643",
"runtimeUser": "test",
"sysId": "6e9791f0d0f541339dad3202e806276f",
"type": "Standard"
}

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 onlyN

exportTable

n/aRecord table information.read onlyN

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

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/response, sysId will be persisted to the database.
  • If retainSysIds="false" and sysId is included in the request/response, 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

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
<credentials>
   <credential exportReleaseLevel="7.2.0.0" exportTable="ops_credentials" version="1">
	<description />
	<name>test</name>
	<opswiseGroups>
		<opswiseGroup>bs1</opswiseGroup>
		<opswiseGroup>bs2</opswiseGroup>
	</opswiseGroups>
	<runtimeKeyLocation />
	<runtimeUser>ops.admin</runtimeUser>
	<sysId>36208a27bda64312a854985314922953</sysId>
	<type>Standard</type>
   </credential>
   <credential exportReleaseLevel="7.2.0.0" exportTable="ops_credentials" version="1">
	<description />
	<name>test 2</name>
	<opswiseGroups>
		<opswiseGroup>bs1</opswiseGroup>
		<opswiseGroup>bs2</opswiseGroup>
	</opswiseGroups>
	<runtimeKeyLocation />
	<runtimeUser>ops.admin2</runtimeUser>
	<sysId>36208a27bda64312a854985314922954</sysId>
	<type>Standard</type>
   </credential>
</credentials>
 JSON Response
[ {
  "description": null,
  "exportReleaseLevel": "7.2.0.0",
  "exportTable": ops_credentials",
  "name": "test",
  "opswiseGroups": ["bs1","bs2"],
  "runtimeKeyLocation": null,
  "runtimeUser": "test",
  "sysId": "6e9791f0d0f541339dad3202e806276f",
  "type": "Standard",
  "version": 1
  },
  {
  "description": null,
  "exportReleaseLevel": "7.2.0.0",
  "exportTable": ops_credentials",
  "name": "test 2",
  "opswiseGroups": ["bs1","bs2"],
  "runtimeKeyLocation": null,
  "runtimeUser": "test 2",
  "sysId": "6e9791f0d0f541339dad3202e806276g",
  "type": "Standard",
  "version": 1
  }
]

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
 <credential>
	<description>Testing/description>
	<name>test</name>
	<opswiseGroups>
		<opswiseGroup>bs1</opswiseGroup>
		<opswiseGroup>bs2</opswiseGroup>
	</opswiseGroups>
	<runtimeKeyLocation />
	<runtimePassPhrase />
	<runtimePassword>ops.admin</runtimePassword>
	<runtimeUser>test</runtimeUser>
	<sysId>36208a27bda64312a854985314922953</sysId>
	<type>Standard</type>
</credential>
 JSON Request
{
  "description": "Testing",
  "name": "test",
  "opswiseGroups": [
    "bs1",
    "bs2"
  ],
  "runtimeKeyLocation": null,
  "runtimePassPhrase": null,
  "runtimePassword": "test",
  "runtimeUser": "test",
  "sysId": "6e9791f0d0f541339dad3202e806276f",
  "type": "Standard"
}

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

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
 <credential exportReleaseLevel="7.2.0.0" exportTable="ops_credentials" retainSysIds="true" version="1">
	<description />
	<name>test</name>
	<opswiseGroups>
		<opswiseGroup>bs1</opswiseGroup>
		<opswiseGroup>bs2</opswiseGroup>
	</opswiseGroups>
	<runtimeKeyLocation />
	<runtimeUser>ops.admin</runtimeUser>
	<sysId>36208a27bda64312a854985314922953</sysId>
	<type>Standard</type>
</credential>
 JSON Response
{
  "description": null,
  "exportReleaseLevel": "7.2.0.0",
  "exportTable": ops_credentials",
  "name": "test",
  "opswiseGroups": ["bs1","bs2"],
  "retainSysIds": true,
  "runtimeKeyLocation": null,
  "runtimeUser": "test",
  "sysId": "6e9791f0d0f541339dad3202e806276f",
  "type": "Standard",
  "version": 1
}