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:

Examples: Get an Entry(curl), Create New Entry (powershell)
Details: OAuth 2FA authentication

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