Call the Web Service using REST

The GetPassword Web Service

The Central Credential Provider offers the following REST web service:

GetPassword – This service enables applications to retrieve secrets from the Central Credential Provider. It has the following structure:

  
GET  /AIMWebService/api/Accounts?<param1>=<value>&<param2>=<value>& ....
HTTP v1.1

 

Description

This service enables applications to retrieve passwords from the Central Credential Provider.

URL

/AIMWebService/api/Accounts?<param1>=<value>&<param2>=<value>& ....

  • Make sure there are no spaces in the URL

  • <value> does not support the following characters: + & %
HTTP Method GET

HTTP Version

1.1
Content Type application/json
Query Parameter  

The following parameters can be specified in the URL to filter the result:

Parameter Purpose Default Type

AppID

Specifies the unique ID of the application issuing the password request.

Note:   This parameter is required.

- String

Safe

Specifies the name of the Safe where the password is stored.

-

String

Folder

Specifies the name of the folder where the password is stored.

Root

String

Object

Specifies the name of the password object to retrieve.

-

String

UserName

Defines search criteria according to the UserName account property.

-

String

Address

Defines search criteria according to the Address account property.

-

String

Database

Defines search criteria according to the Database account property.

-

String

PolicyID

Defines the format that will be used in the setPolicyID method.

-

String

Reason

The reason for retrieving the password. This reason will be audited in the Credential Provider audit log

-

String

Connection Timeout

The number of seconds that the Central Credential Provider will try to retrieve the password.

The timeout is calculated when the request is sent from the web service to the Vault and returned back to the web service.

30

Int
Query Defines a free query using account properties, including Safe, folder, and object. When this method is specified, all other search criteria (Safe/Folder/ Object/UserName/Address/PolicyID/Database) are ignored and only the account properties that are specified in the query are passed to the Central Credential Provider in the password request.

-

String
Query
Format

Defines the query format, which can optionally use regular expressions. Possible values are:

■ Exact
■ Regexp
Exact String
FailRequest OnPassword Change Whether or not an error will be returned if this web service is called when a password change process is underway. False Boolean
 
Result
  
{
"Content": <password>,
"UserName": <username>,
"Address": <address>,
"Database" <Database>,
"PasswordChangeInProcess":<PasswordChangeInProcess>;
}
Status Code: 200

 

 

Only the account properties that are currently defined will be returned.

The following table explains the possible output parameters:

Properties Purpose Type
Content This parameter returns the password content or an empty value if an error occurs. String
UserName Returns the UserName property of the password, or an empty value if this property does not exist or has an empty value. String
Address Returns the Address property of the password, or an empty value if this property does not exist or has an empty value. String
Database Returns the Database property of the password, or an empty value if this property does not exist nor has an empty value. String
PasswordChange
InProcess 		Indicates whether or not a password change is in process. Boolean
Errors

The following errors may occur with the following status codes:

Error Code Status code & use case

APPAP306E

Forbidden (403) // app failed on authentication check
APPAP008E

Forbidden (403) // "ITATS982E User app11 is not defined", etc
APPAP004E NotFound (404) // safe not found, etc
AIMWS030E BadRequest (400) // invalid query format, etc
APPAP227E BadRequest (400) // 1. too many objects
APPAP228E BadRequest (400) // 2. too many objects
APPAP229E

BadRequest (400) // 3. too many objects
APPAP007E BadRequest (400) // Connection to the Vault has failed
APPAP081E BadRequest (400) // Request Message content is invalid
CASVL010E

BadRequest (400) // Invalid characters in User Name
AIMWS031E

BadRequest (400) // Invalid request. The AppID Parameter is required

Example

The following example shows how to use the Central Credential Provider REST Web Service in your code.

  
https://<host:port>/AIMWebService/api/Accounts?AppID=BillingApp&Query=Safe=Billing;Object=MonthlyBilling

In the above example, an application called BillingApp is trying to retrieve an account called MonthlyBilling from the Billing Safe.