Security Controls REST API

Home 

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 and delete credentials.

Base URL

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

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}

 

Success code

     

GET

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

 

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 name}

 

UserCredential

     

POST

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

Request Body

UserCredential

     

PUT

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}

Request Body

Success code

Input Model

Request 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

Local DPApi: Will not work remotely

SessionKey: Protected with an RSA-encrypted session key

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.

Example

Find all credentials created by the current user

GET Request

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

Sample Response

{

"count": 1,

"value": [

{

"id": "01234567-89AB-CDEF-0123-456789ABCDEF",

"links": {

"self": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF"

}

},

"name": "JoesCreds",

"userName": "joe.coder"

}

]

}

Other Request Examples

Add a credential using a clear text password

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

POST Request

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

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.

Find the credential named SampleCred

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials?name=SampleCred

Find the credential with ID 01234567-89AB-CDEF-0123-456789ABCDEF

GET Request

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

Delete the credential with ID 01234567-89AB-CDEF-0123-456789ABCDEF

DELETE Request

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

 

Output Model

UserCredential

Name Type Description

name

String

A friendly name for this credential that describes exactly where it should be used.

password

Password

The password that is associated with the UserName.

userName

String

A user name that has access to the desired machines.

id

Guid

The unique credential identifier that was automatically assigned to the credential. This is read only.

links

Links

Shows the related URL for the credential.


Was this article useful?    

The topic was:

Inaccurate

Incomplete

Not what I expected

Other