Credentials

Credentials consist of a user name and password pair. They are used to access specified target machines in order to perform scans and push any necessary files. You can define new scan credentials, locate existing credentials, share credentials, and delete credentials.

Operations invoked by the REST API run as the Windows System account, which cannot decrypt credentials that are not shared with it. To facilitate this ability, you must provide session credentials for the specified user, as described in Session Credentials.

You can find and view service credentials, which are credentials available to all administrators and are used to access service components within Security Controls. A service credential is created whenever you enable the Enable for background services check box on the Share Credential dialog within Security Controls.

Base URLs

        https://<consoleFQDN:port>/st/console/api/v1.0/credentials
        https://<consoleFQDN:port>/st/console/api/v1.0/servicecredentials

Servicecredentials requests will be deprecated in a future release.

Supported Requests

Method	URL	Input	Return
DELETE	https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}		Success code
DELETE	https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}/share	Share Body	Success code
GET	https://<consoleFQDN:port>/st/console/api/v1.0/credentials	URL Parameters	User credential list
	https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}		UserCredential
	https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}/share		User name list
	https://<consoleFQDN:port>/st/console/api/v1.0/servicecredentials		ServiceCredential
	https://<consoleFQDN:port>/st/console/api/v1.0/servicecredentials/{servicecredential id}		ServiceCredential
POST	https://<consoleFQDN:port>/st/console/api/v1.0/credentials	Credentials Body	UserCredential
POST	https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}/share Only users who have previously logged on to the Security Controls console machine are eligible to be assigned a shared credential.	Share Body	UserCredential
PUT	https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}	Credentials Body	Success code
PUT	https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}/share Only users who have previously logged on to the Security Controls console machine are eligible to be assigned a shared credential.	Share Body	Success code

Input Models

URL Parameters

Name	Type	Description
name	String	Returns the items whose name matches the specified name.

Credentials Body

Name	Required?	Type	Default Value	Description
name	Yes	String	None	Provide a friendly name for this credential that describes exactly where it should be used.
password	Yes	Password	None	Provides the password that is associated with the UserName.
userName	Yes	String	None	Provide a user name that has access to the desired machines.

Password

Name	Description
cipherText	Sets the encrypted password. The type of encryption is determined by ProtectionMode and SessionKey. Mutually exclusive with ClearText.
clearText	Sets the unencrypted password. Mutually exclusive with CipherText.
protectionMode	The type of data protection applied to the password for at-rest security. The valid options are: None: This is the default. ClearText is required. Local DPApi: Will not work remotely. CipherText is also required. SessionKey: Protected with an RSA-encrypted session key. SessionKey and cipherText are also required.
sessionKey	Defines an encrypted session key used to protect the password in transit and at rest. It contains the following fields: algorithmIdentifier: Required. The algorithm URI identifier. Valid values vary based on platform, FIPS compliance and the availability of crypto providers. The best practice is AES. encryptedKey: Required. The base64-encoded, RSA-encrypted session key. iv: The base64-encoded, unencrypted initialization vector used with the session key. It is used to seed the security algorithm.

Share Body

Name	Required?	Type	Default Value	Description
propagateUsagePolicy	No	ENUM	Throw	Specifies the behavior when the shared user has conflicting credential usages. Valid options are: Throw: Throw an error if existing usage exists. Overwrite: Overwrite usage when a usage exists.
propagateUsages	No	Boolean	False	Specifies if the credential usages are propagated to the shared users.
shareWithService	No	Boolean	False	Specifies if the credential and its usages will be shared with background services.
userNames	Yes	String[]	None	Provide the user names with whom the credential will be shared.

Example with Sample Response

Find all credentials created by the current user

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials

Sample Response

Copy

{
    "count": 1,
    "value": [
        {
            "id": "01234567-89AB-CDEF-0123-456789ABCDEF",
            "links": {
                "self": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF"
                },
                "sharewithservice": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF/sharewithservice"
                },
                "share": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF/share"
                }
                "servicecredential": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/servicecredentials/87654321-89AB-CDEF-0123-987654ABCDEF"
                }
            },
            "name": "JoesCreds",
            "ownerName": "Sample\\Administrator",
            "sharedWith": [
                "Sample\\win1",
                "Sample\\Administrator",
                "NT AUTHORITY\\SYSTEM"
                ],
            "sharedWithService": true,
            "userName": "joe.coder"
        }
    ]
}

Other Request Examples

Stop sharing a credential with the specified users

DELETE Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF/share

    {
        "userNames": ["UserA", "UserB", "UserC"]
    }

Add a credential using a clear text password

The password is only in clear text in memory. Passwords sent over the network are encrypted using TLS and are always encrypted in storage.

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/credentials 

    {
        "name": "SampleName", 
        "password":{"ClearText": "SamplePW"}, 
        "userName": "SampleName"
    }

Add a credential using a secure password

This follows the security best practices by encrypting the password while it is in memory. As in the clear text example above, passwords sent over the network are encrypted via TLS and are always encrypted in storage.

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/credentials 

    {
        "name": "SampleName", 
        "password": @{ "cipherText": $cipherText; "protectionMode": "SessionKey"; "sessionKey": "AES" }, 
        "userName": "SampleName"
    }

For more information, see function Add-Credential in the Start-to-Finish Example.

Set a session credential (PowerShell example)

This example shows how to create a credential and then set the session credentials using the previously created credential. For more information about session credentials, see Session Credentials.

Copy

#SetSessionCredentials
$securePassword = ConvertTo-SecureString "secretPassword" -AsPlainText -Force
                    
$global:ExampleRestApiCredential = New-Object System.Management.Automation.PSCredential ("domain\user", $securePassword)
                    
#CreatePSCredential
$pw = @{ClearText = (New-Object PSCredential "user", $global:ExampleRestApiCredential.Password).GetNetworkCredential().Password} | ConvertTo-Json -Depth 20
                    
Invoke-RestMethod -Credential $global:ExampleRestApiCredential https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials -body $pw -Method Post -ContentType "application/json"

Share a credential with the specified users

This request will add to the list of users who are sharing the credential.

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF/share

    {
        "userNames": ["UserA", "UserB", "UserC"]
    }

Share the specified credential with background services

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF/share

    {
        "shareWithService": "true"
    }

Share a credential with the updated set of users

This request will overwrite the list of users who are sharing the credential.

PUT Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF/share

    {
        "userNames": ["UserX", "UserY", "UserZ"]
    }

Output Models

UserCredential

Name	Type	Description
id	Guid	The unique credential identifier that was automatically assigned to the credential. This is read only.
links	Links	Shows the related URLs for the credential.
name	String	A friendly name for this credential that describes exactly where it should be used.
ownerName	String	The account name of the owner.
sharedWith	String[]	Specifies the users with whom this credential has been shared.
sharedWithService	Boolean	Specifies if the credential is shared with background services.
userName	String	A user name that has access to the desired machines.

ServiceCredential

Name	Type	Description
id	Guid	The unique credential identifier that was automatically assigned to the credential. This is read only.
links	Links	Shows the related URLs for the credential.
name	String	A friendly name for this credential that describes exactly where it should be used.
userName	String	A user name that has access to the desired machines.

UserCredentialShares

Name	Type	Description
propagateUsagePolicy	ENUM	Determines the behavior when the shared user has conflicting credential usages. Valid options are: Throw: Throws an error if an existing usage already exists. Overwrite: Overwrite usage when a usage exists.
propagateUsages	Boolean	Specifies if the credential usages are propagated to the shared users.
userNames	String[]	The set of user names.

Name

Type

Description

propagateUsagePolicy

ENUM

Determines the behavior when the shared user has conflicting credential usages. Valid options are:

Throw: Throws an error if an existing usage already exists.
Overwrite: Overwrite usage when a usage exists.

propagateUsages

Boolean

Specifies if the credential usages are propagated to the shared users.

userNames

String[]

The set of user names.