Credential API v2

Credentials can be accessed and modified through this API using four services: GET, POST, PUT, and PATCH. These four services allow for the retrieval, creation, complete update, and partial update of credentials.

Authentication - Use Basic Authentication for this API.

GET

There are two implementations of GET. One will find a Credential with the given Id and return the JSON representation of the Credential. The other will find a list of Credentials matching the parameters supplied to it.

GET by ID

This GET service will find a Credential with the given Id and return the JSON representation of the object.

API URL

http://host:port/flexdeploy/rest/v2/administration/security/credential/{Id}

Request

Parameter
Required
Type
Description
IdYesURLURL parameter for the Id which is used to find and return a Credential

Response Codes

HTTP Code
Description
200Credential was found and returned
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Credential not found
500Unexpected internal server error

Example

If we a Credential in our database with an Id of 11004 and the following attributes

Credential - 11004
{
	"credentialId": 11004,
    "versionNumber": 1,
    "credentialName": "GET Example Name",
    "isActive": true,
    "credentialScope": "ENVINST",
    "credentialStoreId": 11000,
    "credentialInputs": [
        {
            "versionNumber":1,
            "inputValue": "TestPassword",
            "credentialStoreInputDefId": 12000
        }
    ]
}

When we run a GET request at the following URL

http://host:port/flexdeploy/rest/v2/administration/security/credential/11004

The GET request would return the following JSON Credential object

Credential GET Return JSON
{
	"credentialId": 11004,
    "versionNumber": 1,
    "credentialName": "GET Example Name",
    "isActive": true,
    "credentialScope": "ENVINST",
    "credentialStoreId": 11000,
    "credentialInputs": [
        {
            "versionNumber":1,
            "inputValue": "TestPassword",
            "credentialStoreInputDefId": 12000
        }
    ]
}

GET by Query Parameters

This GET service will return a list of Credentials in the form of JSON objects based on the query parameters credentialId, credentialName, credentialScope, and credentialStoreId. Credentials are only returned if they match ALL of the specified query parameters. If no query parameters are given, this request will return the entire list of Credentials. The credentialName parameter returns Credentials that contain the specified parameter. The other parameters must be equal to the Credentials.

API URL

http://host:port/flexdeploy/rest/v2/administration/security/credential?

Append the following character sequences to the above URL to specify Query parameters.
Use '&' between successive query parameters: 

credentialId={credentialId}

credentialName={credentialName}

credentialScope={credentialScope}

credentialStoreId={credentialStoreId}

Examples:
To Specify the NAME parameter only:

http://host:port/flexdeploy/rest/v2/administration/security/credential?credentialName={credentialName}

To Specify the NAME AND SCOPE parameters:

http://host:port/flexdeploy/rest/v2/administration/security/credential?credentialName={credentialName}&credentialScope={credentialScope}

To Specify the name, SCOPE, AND CREDENTIAL STORE ID parameters:

http://host:port/flexdeploy/rest/v2/administration/security/credential?credentialName={credentialName}&credentialScope={credentialScope}&credentialStoreId={credentialStoreId}

The query parameters are not case sensitive. Searching by credentialName=NAME is the same as searching by credentialName=name.

Request

Parameter
Required
Type
Description
credentialIdNoQuery - Long

This is a URL query parameter for the Credential Id which is used to search the Credentials.

Equals search

credentialNameNoQuery - String

This is a URL query parameter for the Credential name which is used to search the Credentials.

Like ignore case search

credentialScopeNoQuery - String

This is a URL query parameter for the Credential Scope which is used to search the Credentials.

Equals ignore case search

credentialStoreIdNoQuery - Long

This is a URL query parameter for the Credential Store Id which is used to search the Credentials.

Equals search

Response Codes

HTTP Code
Description
200Search successful and results returned
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected internal server error

Example

Output when querying by Credential Scope "ENVINST" through http://host:port/flexdeploy/rest/v2/administration/security/credential?credentialScope=ENVINST

Sample JSON Output
[	
	{
		"credentialId": 11004,
    	"versionNumber": 1,
    	"credentialName": "GET Example Name 1",
    	"isActive": true,
    	"credentialScope": "ENVINST",
    	"credentialStoreId": 11000,
    	"credentialInputs": [
        	{
            	"versionNumber":1,
            	"inputValue": "TestPassword",
            	"credentialStoreInputDefId": 12000
        	}
    	]
	},
	{
		"credentialId": 11004,
    	"versionNumber": 1,
    	"credentialName": "GET Example Name 2",
    	"isActive": false,
    	"credentialScope": "ENVINST",
    	"credentialStoreId": 11020,
    	"credentialInputs": [
        	{
            	"versionNumber":1,
            	"inputValue": "TestPassword123",
            	"credentialStoreInputDefId": 13000
        	}
    	]
	},
]

POST

The POST service will create a new Credential with the same attributes as the given JSON object. It returns the JSON representation of the Credential that was just created with an updated ID attribute.

API URL

http://host:port/flexdeploy/rest/v2/administration/security/credential

Request

Attributes
Type
Required
Description
credentialNameStringYesName of Credential.
isActiveBooleanNo

Whether or not this Credential is active. Defaults to true.

credentialScopeStringYes

Scope of the Credential. Possible values are ENDPOINT, INST, or ENVINST.

credentialStoreIdLongYesThe unique id of the associated Credential Store.
credentialInputsList<CredentialInputDataObject>YesList of the Credential Input Data Objects that are associated with this Credential.

CredentialInputDataObject can include the following attributes:

AttributesTypeRequiredDescription
inputValueDepends on inputYesValue for credential input
credentialStoreInputDefIdLongYesId of input definition. Can be found using the Credential Store Provider API.

Response Codes

HTTP Code
Description
201Credential was created successfully
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected internal server error

Example

If the POST receives the following JSON Credential object,

Sample JSON Input
{
    "credentialName": "POST Example Name",
    "isActive": true,
    "credentialScope": "ENVINST",
    "credentialStoreId": 11000,
    "credentialInputs": [
        {
            "inputValue": "TestPassword",
            "credentialStoreInputDefId": 12000
        }
    ]
}

the following Credential will be created in the database. Notice the updated Credential Id field.

Sample JSON Output
{
	"credentialId": 11004,
    "versionNumber": 1,
    "credentialName": "POST Example Name",
    "isActive": true,
    "credentialScope": "ENVINST",
    "credentialStoreId": 11000,
    "credentialInputs": [
        {
			"credentialId": 11004,
			"updatedBy": "fdadmin",
			"updatedOn": "2021-09-10T12:59:34.821+0000",
			"createdBy": "fdadmin",
			"createdOn": "2021-09-10T12:59:34.821+0000",
			"isEncrypted": true,
            "versionNumber":1,
            "inputValue": "*****",
            "credentialStoreInputDefId": 12000,
			"credentialInputId": 284872
        }
    ]
}

PUT

This PUT service will update all attributes of a Credential with the given Id based on the attributes of the supplied JSON object.

API URL

http://host:port/flexdeploy/rest/v2/administration/security/credential/{credentialId}

Request

Attributes
Type
Required
Description
credentialIdURLYesURL parameter for the Id which is used to find and update a Credential.
credentialNameStringYesName of Credential.
isActiveBooleanNo

Whether or not this Credential is active. Defaults to true if nothing is passed.

credentialScopeStringYes

Scope of the Credential. Possible values are ENDPOINT, INST, or ENVINST. Scope cannot be updated with a PATCH request as it is locked in after creation.

credentialStoreIdLongYesThe unique id of the associated Credential Store. Credential store id cannot be updated with a PATCH request as it is locked in after creation.
credentialInputsList<CredentialInputDataObject>YesList of the Credential Input Data Objects that are associated with this Credential. If currently associated Credential Input Data Object(s) are not in input list, those Data Objects will be unassigned from this Credential.

i.e. at the end of successful request, the Credential will have mapped Property Sets matching to input request.

CredentialInputDataObject can include the following attributes:

AttributesTypeRequiredDescription
inputValueDepends on inputYesValue for credential input
credentialStoreInputDefIdLongYesId of input definition. Can be found using the Credential Store Provider API.

Response Codes

HTTP Code
Description
200Credential was found and updated
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Credential not found
500Unexpected internal server error

Example

If we had an Credential in our database with an Id of 11104 and had the following attributes

Current Credential
{
	"credentialId": 11004,
    "versionNumber": 1,
    "credentialName": "PUT Example Name",
    "isActive": true,
    "credentialScope": "ENVINST",
    "credentialStoreId": 11000,
    "credentialInputs": [
         {
			"credentialId": 11004,
			"updatedBy": "fdadmin",
			"updatedOn": "2021-09-09T12:59:34.821+0000",
			"createdBy": "fdadmin",
			"createdOn": "2021-09-09T12:59:34.821+0000",
			"isEncrypted": true,
            "versionNumber":1,
            "inputValue": "*****",
            "credentialStoreInputDefId": 12000,
			"credentialInputId": 284872
        }
    ]
}

When we run a PUT request at the following URL

http://host:port/flexdeploy/rest/v2/administration/security/credential/11104

And the PUT request receives the following JSON Credential object,

Sample JSON Input
{
    "credentialName": "PUT Example Name",
    "isActive": true,
    "credentialScope": "INST",
    "credentialStoreId": 12000,
    "credentialInputs": [
        {
            "inputValue": "TestPassword1234",
            "credentialStoreInputDefId": 12000
        },
		{
            "inputValue": "TestPass1999",
            "credentialStoreInputDefId": 12010
        }
    ]
}

The PUT request would then update the Credential with Id 11104 and return the following JSON Credential object.

Sample JSON Output
{
	"credentialId": 11004,
    "versionNumber": 1,
    "credentialName": "PUT Example Name",
    "isActive": true,
    "credentialScope": "INST",
    "credentialStoreId": 12000,
    "credentialInputs": [
         {
			"credentialId": 11004,
			"updatedBy": "fdadmin",
			"updatedOn": "2021-09-10T12:59:34.821+0000",
			"createdBy": "fdadmin",
			"createdOn": "2021-09-10T12:59:34.821+0000",
			"isEncrypted": true,
            "versionNumber":1,
            "inputValue": "*****",
            "credentialStoreInputDefId": 12000,
			"credentialInputId": 24895
        },
		 {
			"credentialId": 11004,
			"updatedBy": "fdadmin",
			"updatedOn": "2021-09-10T12:59:34.821+0000",
			"createdBy": "fdadmin",
			"createdOn": "2021-09-10T12:59:34.821+0000",
			"isEncrypted": true,
            "versionNumber":1,
            "inputValue": "*****",
            "credentialStoreInputDefId": 12010,
			"credentialInputId": 284872
        }
    ]
}

PATCH

This PATCH service will update the information of the Credential of the specified Id with the non-null parameters of the JSON. The parameters that are null or missing will not be changed in the Credential.

API URL

http://host:port/flexdeploy/rest/v2/administration/security/credential/{credentialId}

The only required attribute is the Credential Id in the URL.

Request

Attributes
Type
Required
Description
credentialIdURLYesURL parameter for the Id which is used to find and update a Credential.
credentialNameStringNoName of Credential.
isActiveBooleanNo

Whether or not this Credential is active.

credentialScopeStringNo

Scope of the Credential. Possible values are ENDPOINT, INST, or ENVINST. Scope cannot be updated with a PATCH request as it is locked in after creation.

credentialStoreIdLongNoThe unique id of the associated Credential Store. Credential store id cannot be updated with a PATCH request as it is locked in after creation.
credentialInputsList<CredentialInputDataObject>NoList of the Credential Input Data Objects that are associated with this Credential. 

If input Credential Input Data Object(s) is not already associated, it will be associated to Credential but existing Data Object assignment that are not in PATCH request will not be unassigned.

i.e. input list is considered as append to existing assignments.

CredentialInputDataObject can include the following attributes:

AttributesTypeRequiredDescription
inputValueDepends on inputYesValue for credential input
credentialStoreInputDefIdLongYesId of input definition. Can be found using the Credential Store Provider API.

Response Codes

HTTP Code
Description
200Credential was found and patched
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
404Credential not found
500Unexpected internal server error

Example

If we had a Credential in our database with an Id of 11104 and had the following attributes

Current Credential
{
	"credentialId": 11004,
    "versionNumber": 1,
    "credentialName": "PUT Example Name",
    "isActive": true,
    "credentialScope": "INST",
    "credentialStoreId": 11000,
    "credentialInputs": [
         {
			"credentialId": 11004,
			"updatedBy": "fdadmin",
			"updatedOn": "2021-09-09T12:59:34.821+0000",
			"createdBy": "fdadmin",
			"createdOn": "2021-09-09T12:59:34.821+0000",
			"isEncrypted": true,
            "versionNumber":1,
            "inputValue": "*****",
            "credentialStoreInputDefId": 12000,
			"credentialInputId": 284895
        }
    ]
}

When we run a PATCH request at the following URL

http://host:port/flexdeploy/rest/v2/administration/security/credential/11104

And the PATCH request receives the following JSON Credential object,

Current Credential
{
    "credentialScope": "INST",
    "credentialInputs": [
        {
            "versionNumber":1,
            "inputValue": "TestPass1999",
            "credentialStoreInputDefId": 12010
        }
    ]
}

The PATCH request would then update the Credential with Id 11104 and return the following JSON Credential object.

Only the fields present in the PATCH JSON will modify the original JSON Credential object. All other fields will remain unchanged.

Sample JSON Output
{
	"credentialId": 11004,
    "versionNumber": 1,
    "credentialName": "PUT Example Name",
    "isActive": true,
    "credentialScope": "INST",
    "credentialStoreId": 11000,
    "credentialInputs": [
         {
			"credentialId": 11004,
			"updatedBy": "fdadmin",
			"updatedOn": "2021-09-09T12:59:34.821+0000",
			"createdBy": "fdadmin",
			"createdOn": "2021-09-09T12:59:34.821+0000",
			"isEncrypted": true,
            "versionNumber":1,
            "inputValue": "*****",
            "credentialStoreInputDefId": 12000,
			"credentialInputId": 284895
        },
		 {
			"credentialId": 11004,
			"updatedBy": "fdadmin",
			"updatedOn": "2021-09-10T12:59:34.821+0000",
			"createdBy": "fdadmin",
			"createdOn": "2021-09-10T12:59:34.821+0000",
			"isEncrypted": true,
            "versionNumber":1,
            "inputValue": "*****",
            "credentialStoreInputDefId": 12010,
			"credentialInputId": 284872
        }
    ]
}