Sitemap

RESTful API

Users prefer Pleasant Password Server with a KeePass client!

The REST API provides programmatic access to Pleasant Password Server using OAuth2 for authorization. 

All API methods (except the Authorization API) can both accept and return either JSON or XML. This must be specified through the "Accept" header. The full URL of the API should consist of:

  • https://[domain]:[port]/api/{version}/rest/

  • Version:
    • /v6/  - Version 6 for Password Server 7.11 or higher
    • /v5/  - Version 5 for Password Server 7.9.7 or higher
    • /v4/  - Version 4 for Password Server 7.0 or higher
    • /v3/  - Version 3 for previous versions

Have Questions?  Contact Us

Related Links:

API Version 4

The following are particular to versions 7 and higher.

Authorization

Authorization uses a different endpoint from the rest of the API, it is as follows:

  • https://[domain]:[port]/OAuth2/Token

 

POST OAuth2/Token Acquire an authorization token for a user.
Method POST
   
Form Encoded Parameters  
    grant_type Must be "password".
    username  
    password  
   
Success result  
    access_token The authorization token used for subsequent authentications.
    token_type Always "bearer".
    expires_in The amount of seconds the bearer token is valid for.
   
Error result (400 Bad Request)  
    error Error code name.
    error_description Error code description.
   

If an error occurs and it is a result of two-factor authentication being enabled, the following parametes will be found in the response headers:

    X-Pleasant-OTP: "required"
    X-Pleasant-OTP-Provider: An identifier for the two-factor provider expected

 

POST OAuth2/Token Acquire an authorization token for a user using two-factor authentication.
Method POST
   
Header Encoded Parameters  
    X-Pleasant-OTP The two-factor token value.
    X-Pleasant-OTP-Provider Two-factor provider.
   
Success result  
    access_token The authorization token used for subsequent authentications.
    token_type Always "bearer".
    expires_in The amount of seconds the bearer token is valid for.
   
Error result (400 Bad Request)  
    error Error code name.
    error_description Error code description.


Once you aquire an access token, a header parameter "Authorization" must be set to the authorization token for all subsequent API calls. See:

General

GET configuration/:client Returns the server-enforced client configuration.
Method GET
Requires Authentication? Yes
   
Parameters  
    client  
   
Result type Client Config

 

PUT currentuser/password Change the current user's password.
Method PUT
Requires Authentication? Yes
   
Parameters  
    oldpassword  
    newpassword  
   
Result type None

 

POST passwordstrength Returns a numerical rating for a password's strength.
Method POST
Requires Authentication? Yes
   
Parameters  
    password  
   
Result type Password Strength

 

POST search Returns a list of credentials and groups matching a specified query.
Method POST
Requires Authentication? Yes
   
Parameters  
    search  
   
Result type Search Result

 

POST iscommentrequired/:id Check if a usage comment is required for an action.
Method POST
Requires Authentication? Yes
   
Parameters  
    id The GUID of the object being checked (should be an empty guid for the ViewOffline action)
    actionName Possible values:
  * ViewEntryPassword
  * ModifyEntries
  * ModifyFolderNames
  * DeleteEntries
  * DeleteFolders
  * MoveEntries
  * MoveFolders
  * GrantPermissions
  * ViewOffline
  * ModifyCommentSettings
  * ModifyProxySettings
  * ModifyNotificationSettings
  * ModifyPasswordAutoChangeSettings
   
Result type Boolean

 

GET isofflineavailable Check if a user has the ability to get offline access to credentials.
Method GET
Requires Authentication? Yes
   
Result type Boolean

 

GET about Get information about the server.
Method GET
Requires Authentication? Yes
   
Result type About Server

Credential

Common mistakes:

  • Creating a credential or credential group using POST http method, not the PUT http method
  • Likewise for updates, use the PUT http method, not the POST http method.

 

GET credential/:id Read a credential.
Method GET
Requires Authentication? Yes
   
Parameters  
id GUID for credential
   
Result type Credential

  

DELETE credential/:id Delete a credential.
Method DELETE
Requires Authentication? Yes
   
Parameters  
id GUID for credential
   
Result type None

 

POST credential ** Create a credential **
Method POST
Requires Authentication? Yes
   
Input type Credential
Result type GUID

 

PUT credential/:id ** Update a credential **
Method PUT
Requires Authentication? Yes
   
Parameters  
id GUID for credential
   
Input type Credential
Result type None

 

GET credential/:id/password Get the password for a credential.
Restriction Can only be used when a usage comment is not required.
Method GET
Requires Authentication? Yes
   
Parameters  
id GUID for credential
   
Result type String

 

POST credential/:id/password Get the password for a credential.
Method POST
Requires Authentication? Yes
   
Parameters  
id GUID for credential
comment Usage comment may be optional or a required field. 
  See Usage Comments for details.
   
Result type String

Credential Groups

Common mistakes: to create a credential or credential group use the POST http method, not the PUT http method. Likewise for updates, use the PUT http method, not the POST http method.

 

GET credentialgroup/:id Read a credential group.
Method GET
Requires Authentication? Yes
   
Parameters  
id Optional. GUID for credential group.
  If passed in, direct descendents will be included in the result.
  If not passed in, the entire password hierarchy will be returned.
   
Result type Credential Group

 

DELETE credentialgroup/:id Delete a credential group.
Method DELETE
Requires Authentication? Yes
   
Parameters  
id GUID for credential group
   
Result type None

 

POST credentialgroup ** Create a credential group **
Method POST
Requires Authentication? Yes
   
Input type Credential Group
Result type Guid

 

PUT credentialgroup/:id ** Update a credential group **
Method PUT
Requires Authentication? Yes
   
Parameters  
id GUID for credential group
   
Input type Credential Group
Result type None

 

GET credentialgroup/root Read the root credential group.
Method GET
Requires Authentication? Yes
   
Result type Credential Group