1. Overview

    The Passwordstate API is a HTTP Based Services interface, providing programmatic access to much of the data in the system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities to gadgets to the browser URL bar itself.

     Note: If you update any of the following options on the screen Administration -> System Settings within Passwordstate, you may need to restart the Passwordstate web site in IIS as the API "may" have any one of the following values cached in memory.
    1. Bad Password Strength Indicator option on 'Password Options' tab.
    2. Use regular expressions when matching 'Bad Passwords' option on 'Miscellaneous' tab.
    3. Validate passwords are in sync option on 'Active Directory Options' tab.
  2. Authentication

    All API requests must contain some mechanism for authorizing requests to data, for which the Passwordstate API uses API keys for this purpose. Each Password List can have its own unique API key, and must be passed in each request for a valid response to be received. In additional to each Password List having its own API Key, you can set a 'System Wide' API Key on the System Settings screen within Passwordstate.

    Creating Password Lists API keys

    A unique API key can be created per Password List, by editing the settings for a Password List, and then clicking on the API Key tab.

    Creating System Wide API key(s)

    Various System Wide API keys can be created in the 'System Settings' section of Passwordstate, and these keys can be used to:

    General API Key: To retreive/update/delete/add records to all Password Lists within the system, return Password History and documents, and create Password Lists and Folders
    Hosts API Key: To add or delete Hosts from the system
    Password Generator API Key: To generate random passwords

    Note: Access to the main System Wide API Key should not be given out to unauthorized users due to the privilege level it has.

    Restricting API Keys from being specified in QueryStrings

    API Keys can either be specified in the QueryString of the URL method call, or within the Header Request - It is more secure to include the API Key in the Header Request, as the key will be encrypted in transit.

    If you want to prevent users from incuding the API Key in the QueryString URL, you can go to the screen Administration -> System Settings -> API Keys, and disable the option here.

    Using the API Key(s)

    To authenticate majority of requests, you must specify the relevant API Key and associated ID value. i.e. PasswordListID and API Key. The 'System Wide' API Key can also be used in replacement of the Password List API Key if needed.

    An example query for a Password List's details are:

        # curl Request
        curl https://passwordstate/api/passwordlists/<PasswordListID>?apikey=<apikey>
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "AllowExport": true,
                "AuthenticationPerSession": false,
                "AuthenticationType": "None Required",
                "CodePage": "Unicode (UTF-8)",
                "Description": "Various web sites on the net",
                "ForcePasswordGenerator": false,
                "GeneratorName": "Default Password Generator",
                "Guide": "",
                "HandshakeApprovalRequired": false,
                "HidePasswords": false,
                "ImageFileName": "internet.png",
                "PasswordGeneratorID": 1,
                "PasswordList": "Web Site's",
                "PasswordListID": 27,
                "PasswordResetEnabled": false,
                "PasswordStrengthPolicyID": 7,
                "PolicyName": "SQL Server Policy",
                "PreventBadPasswordUse": true,
                "PreventDragDrop": true,
                "PreventExpiryDateModification": false,
                "PreventPasswordReuse": 5,
                "PrivatePasswordList": false,
                "ProvideAccessReason": true,
                "ResetExpiryDate": 0,
                "SetExpiryDate": 0,
                "ShowGuide": false,
                "TimeBasedAccessRequired": false,
                "TotalPasswords": 23,
                "TreePath": "\ISP Accounts"
            }
        ]
              

    API Key in QueryString or Request Header

    There are two methods in which you can pass the value of the API Key - either in the querystring URL itself, or the Request Header.
    To enter in the Request Header, use the format of :

    Content-Type: application/json
    APIKey: <apikey>

     Recommended: The more secure option is to supply the API Key in the Request Header. Any parameters passed in the URL of an encrypted transport layer (SSL Certificate) will also be encrypted, but there are certain scenarios where the URL can be saved/retained in unencrypted plain text format, and they are:

    • URLs are stored in the browser history
    • URLs are stored in the web server logs
    • URLs are passed in Referrer headers
    • "Man in the middle" attacks using various tools
    • URLs are stored in a browser bookmark, if created

     Note: The remaining documentation shows the API Key as being passed in the URL querystring, for readability sake. Please pass in the Request Header instead - if possible.

        # curl Syntax
        curl https://passwordstate/api/passwordlists/<PasswordListID> --header "APIKey: <apikey>"
                       
        # PowerShell Syntax
        Invoke-Restmethod -Uri https://passwordstate/api/passwordlists/<PasswordListID> -Header @{ "APIKey" = "<apikey>" }
        
  3. Errors

    Sometimes requests to the API are not successful - failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code that indicates the nature of the failure (below), with a response body in JSON format containing additional information. Failed API calls also record an Audit Event in Passwordstate which can be queried and reported on.

    200 Success. If data was requested, it will be available in the data field at the top level of the response body.
    201 Success (for object creation). Its information is available in the data field at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response.
    204 No Content. Successful deletion of a record.
    400 Invalid request. Issues with Parameters - This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
    401 No authorization. APIKey Issues - A valid API key was not provided with the request, so the API could not associate a user with the request, or a Password with a Password List, etc.
    403 Forbidden. Failed some form of 'compliance' check when adding/updating data, or the API key and request syntax was valid but the server is refusing to complete the request - This can happen if you try to read or write to objects or properties that the user does not have access to.
    404 Not found. Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.
    500 Server error. There was a problem on Passwordstate web site.

    In the event of an error, the response body will contain an errors field at the top level. This contains an array of at least one error object, described below:

    message The type of HTTP Error description i.e. Not Found, No Authorization, etc
    phrase A description of the error. i.e. Invalid API Key, or record does not exist in the database, etc

  4. Input/Output Options

    In addition to providing fields and their values in a request, you may also specify options to control how your request is interpreted and how the response is generated. For GET requests, you can specify options in the URL parameters to return data in either JSON or XML format.

    format options: JSON or XML (JSON is the default format type if none are specified as a URL parameter)
    Important: You must specify the ContentType correctly for the formatted data you are inputting, otherwise the API call will fail.
    Boolean Fields: Boolean fields must be specified in the lowercase format i.e. true and false, not True and False.

     Important JSON Note: If you are passing JSON data in a HTTP POST or PUT, then any backslahes need to be double-escaped i.e. Domain\\UserName.

        # curl Request (GET - Retrieving Data)
        curl https://passwordstate/api/passwordlists/<PasswordListID>?apikey=<apikey>&format=<json or xml>    
        
        # curl Request (PUT - Updating Data)
        curl --request PUT https://passwordstate/api/passwords \
           -d "PasswordID=46411" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c" \
           -d "password=ZHn#3+A^yc"   
        
        # Powershell Request (GET - Retrieving Data)
        Invoke-Restmethod -Uri https://passwordstate/api/passwordlists/<PasswordListID>?apikey=<apikey>&format= /
                        <json or xml>  -Method Get
                        # Powershell Options (Append after -Method Get)
        1. Display console output in Json format: | ConvertTo-Json
        2. Pipe console output to a file: | Out-File c:\temp\output.txt
        3. Pipe console output in Json format to a file: -OutFile c:\temp\output.json
        
        # Powershell Request (PUT - Updating Data)
        $jsonString = @'
        {
            "PasswordID":"46411",
            "Password":"JENN-ZHn#3+A^yc",
            "APIKey":"be497cfa86352d5d67e3b4c8a29fc4b5"
        }
        '@
             
        Invoke-Restmethod -Method Put -Uri https://passwordstate/api/passwords/ -ContentType "application/json" /
           -Body $jsonString
        

    ContentType Example with Fiddler
    The following screenshot is an example, using Fiddler, of how you specify a ContentType for your data when Posting data to the API.

    The text is included here for your convenience so you can cut and paste if required: Content-Type: application/json

  5. Reference

    The following API References details which methods are available to you in retrieving and updating data in Passwordstate. It includes information such as expected HTTP Verbs, URL syntax, Input and Output Parameters, and example data output.
  6. Folders

    Folders are used to logically group one or more Password Lists, or other Folders, in the main Password Lists Navigation Tree within the Passwordstate User Interface.

    Adding a New Folder

    POST /api/folders

    Adding a new Folder object can be achieved by making a POST request on the URL, with appropriate fields forming the HTTP message body. To create Folders, you must use the System Wide API Key.

    This method returns the new Folder object as described above. The newly created FolderID can then be used in futher processing when adding Password Lists, to nest these new Password Lists beneath the newly created Folder.

        # curl Request
        curl --request POST https://passwordstate/api/folders 
           -d "FolderName=Northern Region Customers" \
           -d "Description=Folder for all Northern Customer Password Lists" \
           -d "CopyPermissionsFromPasswordListID = 34" \
           -d "CopyPermissionsFromTemplateID = " \
           -d "NestUnderFolderID = 172" \
           -d "PropagatePermissions = false" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c"
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "FolderID": 181,
                "FolderName": "Northern Region Customers",
                "Description": "Folder for all Northern Customer Password Lists"
            }
        ]
        
    When creating a new Folder, there are a few options for copying permissions and also for placement of the Folder in the Password List Navigation Tree:
    CopyPermissionsFromPasswordListID Data Type: String
    Description: To copy permissions to the Folder from an existing Password List, you can specify the PasswordListID value for this field

    Note 1: By default, Folders inherit permissions from any nested Password Lists beneath them. So if you intend to create a Password List nested beneath this folder, you may not need to copy any permissions here
    Note 2: If you are nested this Folder beneath another Folder which is propagating its permissions down, then you cannot copy permissions from an existing Password List
    CopyPermissionsFromTemplateID Data Type: String
    Description: To copy permissions to the Folder from an existing Password List Template, you can specify the TemplateID value for this field

    Note 1: By default, Folders inherit permissions from any nested Password Lists beneath them. So if you intend to create a Password List nested beneath this folder, you may not need to copy any permissions here
    Note 2: If you are nested this Folder beneath another Folder which is propagating its permissions down, then you cannot copy permissions from an existing Password List Template
    NestUnderFolderID Data Type: String
    Description: If you would like this newly created Folder to be nested beneath another Folder or Password List, specify the FolderID or PasswordList value here. If omitted, the Folder will be created in the root of the Navigation Tree - which is equivalent to the value of 0.
    PropagatePermissions Data Type: Boolean
    Description: If you want the folder to propagate its permissions down to all nested Password Lists and Folders, then you set PropagatePermissions to true.

    Note 1: This option can only be enabled for top level folders i.e. nested under Passwords Home
    Note 2: If using this option, you still need to copy permissions from an existing Password List or Template


    Search for Folders

    GET /api/folders

    Searching for Folders can be achieved via multiple criteria, as outlined by the fields below. You can search using just one field, or multiple to further narrow down the search results. In order to search for Folders, you must specify the System Wide API Key which can be found on the screen Administration -> System Settings -> API Keys tab.

    • FolderName
    • Description
    • TreePath

        # Search by Folder Name
        curl https://passwordstate/api/folders/?FolderName=<value>&apikey=<value>
                                    
        # Search by Description 
        curl https://passwordstate/api/folders/?Description=<value>&apikey=<value>
        
        # Search by TreePath
        curl https://passwordstate/api/folders/?TreePath=<value>&apikey=<value>
    
        
    The following example shows, in PowerShell, shows how to search by Folder Name, and speciying the API Key in the Header Request.
        # Powershell Request (GET)
        $PasswordstateURL = 'https://passwordstate/api/folders/?FolderName=<value>'
        $result = Invoke-Restmethod -Method GET -Uri $PasswordstateURL -Header @{ "APIKey" = "<value>" }
        Write-Output $result
    
       
        # Response
        HTTP/1.1 200           
        [
            {
                "FolderID":86,
                "FolderName":"Contoso",
                "Description":"All passwords for customer Contoso",
                "TreePath":"\Customers\Contoso"
            }
        ]
    

    Password Lists

    The Password List is the basic object around which many operations in Passwordstate are centered. A Password List represents a collection of related password objects, and has many associated settings which can modify the behaviour of interacting with the Password List.

    Password Lists have a rich set of metadata associated with them, some of which are exposed via the API. Here are the accessible fields on a Password List:

    PasswordListID Data Type: Integer
    Description: Unique identifier for the Password List
    Read-only: The time at which the Password List was created.
    PasswordList Data Type: String (50)
    Description: A title to describe the nature of the Password List
    Description Data Type: String (255)
    Description: A longer verbose description of the nature of the Password List
    ImageFileName Data Type: String (50)
    Description: The filename of an image associated with the Password Lists (All files are stored in the /images/lookupimages folder for the Passwordstate web install).
    Guide Data Type: String (8000)
    Description: Any associated instructions (guide) for how the Password List should be used (Can contain HTML characters).
    AllowExport Data Type: Boolean
    Description: Indicates whether users are able to export Passwords from the Password List through the web interface.
    PrivatePasswordList Data Type: Boolean
    Description: Indicates whether the Password List is Private only to the user who created the Password List.
    TimeBasedAccessRequired Data Type: Boolean
    Description: Indicates whether Time-based Access settings are required when applying new permissions to this Password List.
    HandshakeApprovalRequired Data Type: Boolean
    Description: Indicates whether two Password List Administrators must approve access to the Password List, prior to access being given.
    PasswordStrengthPolicyID Data Type: Integer
    Description: The ID value representing the Password Strength Policy settings associated with this Password List (derived from the PasswordStrengthPolicies table).
    PasswordGeneratorID Data Type: Integer
    Description: The ID value representing the Password Generator settings associated with this Password List (derived from the PasswordGenerators table).
    CodePage Data Type: String ()
    Description: Indicates the character-set associated with the Password List (used when importing and exporting data from the List). Reference for code page options can be found here - Code Page Identifiers.
    PreventPasswordReuse Data Type: Integer
    Description: If a value other than 0 (zero) is specified, the user will not be able to re-use the last (x) number of Password values for a given Password object.
    AuthenticationType Data Type: Integer
    Description: Indicates whether an additional authentications step is required prior to users being able to access the Password objects stored in the Password List. Possible values are:
    0 - None Required
    1 - Use Separate Password
    2 - Use Active Directory Authentication
    3 - Use ScramblePad Authentication
    4 - Use Forms Based Authentication
    AuthenticationPerSession Data Type: Boolean
    Description: When set to true, any addition Authentication settings specified above will only need to be satisfied once during the users web session. If set to False, every access to the Password List will require re-authentication.
    PreventExpiryDateModification Data Type: Boolean
    Description: When set to true, only Administrators of the Password List will be able to make modifications to the ExpiryDate field for Password objects.
    ResetExpiryDate Data Type: Integer
    Description: Indicates the number of days which will be added to the ExpiryDate field for Passwords when the Password object is updated (specify 0 means the ExpiryDate field will not be updated).
    PreventDragDrop Data Type: Boolean
    Description: When set to true, only Administrators of the Password List are able drag-n-drop the Password List around in the Navigation Tree
    PreventBadPasswordUse Data Type: Boolean
    Description: When set to true, the user will not be able to saving Password if a 'Bad Password' is detected (Bad Passwords settings and values are controlled by the Security Administrators of Passwordstate).
    ProvideAccessReason Data Type: Boolean
    Description: Indicates whether the user must manually specify the reason why they need access to a Password resource - will prompt them for input via they web interface when they wish to view/edit/update the Password.
    TreePath Data Type: String (NA)
    Description: Represents the hierarchical tree structure the Password List is organized within.
    Read-only: Calculated field.
    TotalPasswords Data Type: Integer
    Description: Represents the total number of Passwords stored in the Password List.
    Read-only: Calculated field.
    GeneratorName Data Type: String (NA)
    Description: The name of the Password Generator associated with the Password List (derived from the PasswordStrengthPolicies table).
    Read-only: Data extracted from different table.
    PolicyName Data Type: String (NA)
    Description: The name of the Password Strength Policy associated with the Password List (derived from the PasswordStrengthPolicies table).
    Read-only: Data extracted from different table.
    PasswordResetEnabled Data Type: Boolean
    Description: Indicates whether the passwords stored in the Password List can be configured to perform resets on remote systems.
    ForcePasswordGenerator Data Type: Boolean
    Description: Indicates the selected Password Generator Policy for the Password List is the only one which can be used to generate random passwords
    HidePasswords Data Type: Boolean
    Description: Indicates that password values in the User Interface will be hidden, so they cannot be viewed or copied to the clipboard
    ShowGuide Data Type: Boolean
    Description: If set to True, the Guide will popup in the User Interface every time a user accesses the Passwor List.
    EnablePasswordResetSchedule Data Type: Boolean
    Description: Provides the default value for enabling a schedule for resets for all new password records added to the Password List.
    PasswordResetSchedule Data Type: String (NA)
    Description: Provides the default value for the schedule of password resets for all new password records added to the Password List.
    AddDaysToExpiryDate Data Type: Integer
    Description: Provides the default value for adding (x) number of days to the ExpiryDate field for all new password records added to the Password List..

    Adding a New Shared Password List

    POST /api/passwordlists

    Adding a new Shared Password List object can be achieved by making a POST request on the URL, with appropriate fields forming the HTTP message body. To create Password Lists, you must use the System Wide API Key.

    This method returns the new Password List object as described above.

        # curl Request
        curl --request POST https://passwordstate/api/passwordlists
           -d "PasswordList=Windows Servers" \
           -d "Description=Local Admin accounts for all Windows Servers" \
           -d "CopySettingsFromPasswordListID = 34" \
           -d "CopySettingsFromTemplateID = " \
           -d "LinkToTemplate = false" \
           -d "CopyPermissionsFromPasswordListID = 34" \
           -d "CopyPermissionsFromTemplateID = " \
           -d "NestUnderFolderID = 128" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c"
    
        OR (to add a Private Password List for a user)
    
        curl --request POST https://passwordstate/api/passwordlists
           -d "PasswordList = John Melvin's Private List" \
           -d "Description = Personal Passwords" \
           -d "ApplyPermissionsForUserID = domain\jmelv" \
           -d "Permission = A" \
           -d "PrivatePasswordList = true" 
           -d "NestUnderFolderID = 0" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c"
        
    The following example shows, in PowerShell, how to create a new Folder, and then a new Password List, and nest the new Password List beneath the new Folder.

    Note: The \ after -ContentType is to indicate a line break so the code is displayed correctly on this page.
        # Powershell Request (POST)
        #JSON data for the new folder
        $jsonFolder = '
        {
    	    "FolderName":"Test Folder",
    	    "Description":"First API Folder",
    	    "CopyPermissionsFromPasswordListID":"4",
    	    "CopyPermissionsFromTemplateID":"",
    	    "NestUnderFolderID":"85",
    	    "APIKey":"8e796d2b543fac8f57b23cae49d6fc58"
        }
        '
        $result = Invoke-Restmethod -Method Post -Uri https://passwordstate/api/folders -ContentType \
                  "application/json" -Body $jsonFolder
        $FolderID = $result.FolderID
    
        #JSON data for the new Password List
        $jsonPasswordList = '
        {
    	    "PasswordList":"Windows S2012",
    	    "Description":"Windows Servers 2012",
    	    "CopySettingsFromPasswordListID":"183",
    	    "CopySettingsFromTemplateID":"",
    	    "LinkToTemplate":false,
    	    "CopyPermissionsFromPasswordListID":"4",
    	    "CopyPermissionsFromTemplateID":"",
    	    "NestUnderFolderID":"' + $FolderID + '",
    	    "APIKey":"8e796d2b543fac8f57b23cae49d6fc58"
        }
        '
    
        $result = Invoke-Restmethod -Method Post -Uri https://passwordstate/api/passwordlists -ContentType \ 
                  "application/json" -Body $jsonPasswordList
        $PasswordListID = $result.PasswordListID
    
       
        # Response
        HTTP/1.1 200           
        [
                "PasswordListID": 27,
                "PasswordList": "Web Site's",
                "Description": "Various web sites on the net",
                "ImageFileName": "internet.png",
                "Guide": "",
                "AllowExport": true,
                "PrivatePasswordList": false,
                "TimeBasedAccessRequired": false,
                "HandshakeApprovalRequired": false,
                "PasswordStrengthPolicyID": 7,
                "PasswordGeneratorID": 1,
                "CodePage": "Unicode (UTF-8)",
                "PreventPasswordReuse": 5,
                "AuthenticationType": "None Required",
                "AuthenticationPerSession": false,
                "PreventExpiryDateModification": false,
                "SetExpiryDate": 0,
                "ResetExpiryDate": 0,
                "PreventDragDrop": true,
                "PreventBadPasswordUse": true,
                "ProvideAccessReason": true,
                "TreePath": "\ISP Accounts",
                "TotalPasswords": 23,
                "GeneratorName": "Default Password Generator",
                "PolicyName": "SQL Server Policy",
                "PasswordResetEnabled": false,           
                "ForcePasswordGenerator": false,
                "HidePasswords": false,            
                "ShowGuide": false,
                "EnablePasswordResetSchedule": false,
                "PasswordResetSchedule": "05:30",
                "AddDaysToExpiryDate": 120
            }
        ]
        
        # Powershell Request (POST)
        #To add a Private Password List for a user
    
        #JSON data for the new Password List
        $jsonPasswordList = '
        {
    	    "PasswordList":"John Melvin's Private List",
    	    "Description":"Personal Passwords",
    	    "ApplyPermissionsForUserID":"domain\\jmelv",
    	    "Permission":"A",
    	    "PrivatePasswordList":"True",
    	    "NestUnderFolderID":"0",
    	    "APIKey":"8e796d2b543fac8f57b23cae49d6fc58"
        }
        '
        $result = Invoke-Restmethod -Method Post -Uri https://passwordstate/api/passwordlists -ContentType \ 
                  "application/json" -Body $jsonPasswordList
        $PasswordListID = $result.PasswordListID
    
    When creating a new Password List, there are a few options for copying settings and permissions from other Password Lists or Templates, where to place the Password List in the Navigation Tree, and if you want to link the Password List to a Template:
    CopySettingsFromPasswordListID Data Type: String
    Description: To copy settings and field configurations to the Password List from an existing Password List, you can specify the PasswordListID value for this field

    CopySettingsFromTemplateID Data Type: String
    Description: To copy settings and field configurations to the Password List from an existing Password Template, you can specify the TemplateID value for this field

    LinkToTemplate Data Type: String
    Description: If you want to Link the new Password List to an existing Password List Template, then you can specify the TemplateID here

    Note: When doing this, you must also specify a value for the field CopySettingsFromTemplateID, and not use the field CopySettingsFromPasswordListID
    CopyPermissionsFromPasswordListID Data Type: String
    Description: To copy permissions to the Password List from an existing Password List, you can specify the PasswordListID value for this field

    CopyPermissionsFromTemplateID Data Type: String
    Description: To copy permissions to the Password List from an existing Password List Template, you can specify the TemplateID value for this field

    NestUnderFolderID Data Type: String
    Description: If you would like this newly created Password List to be nested beneath another Folder or Password List, specify the FolderID or PasswordList value here. If omitted, the Password List will be created in the root of the Navigation Tree - which is equivalent to the value of 0.

    Note: If you are nested this Password List beneath a Folder structure which is propagating its permissions down, then you cannot use any of the CopyPermissionsFrom properties.
    PrivatePasswordList Data Type: String
    Description: To create either a Shared or Private Password List - specify True or False.

    Note: When creating a Private Password List for a user, you cannot copy permissions from other Password List or Template, or apply permissions based on a Security Group.
    ApplyPermissionsForUserID Data Type: String
    Description: Specified which User will be given permission to this newly created Password List.

    ApplyPermissionsForSecurityGroupID Data Type: String
    Description: Specified which Security Group will be given permission to this newly created Password List.

    Permission Data Type: String
    Description: When apply permissions to the newly created Password List (for a User or Security Group), you must specify the values of A, M or V - Administrator, Modify or View rights.

    Retrieving a Password List

    GET /api/passwordlists

    You can retrieve an existing Password List using its ID and APIKey values with a simple GET request.

        # curl Request
        curl https://passwordstate/api/passwordlists/<PasswordListID>?apikey=<value>
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "PasswordListID": 27,
                "PasswordList": "Web Site's",
                "Description": "Various web sites on the net",
                "ImageFileName": "internet.png",
                "Guide": "",
                "AllowExport": true,
                "PrivatePasswordList": false,
                "TimeBasedAccessRequired": false,
                "HandshakeApprovalRequired": false,
                "PasswordStrengthPolicyID": 7,
                "PasswordGeneratorID": 1,
                "CodePage": "Unicode (UTF-8)",
                "PreventPasswordReuse": 5,
                "AuthenticationType": "None Required",
                "AuthenticationPerSession": false,
                "PreventExpiryDateModification": false,
                "SetExpiryDate": 0,
                "ResetExpiryDate": 0,
                "PreventDragDrop": true,
                "PreventBadPasswordUse": true,
                "ProvideAccessReason": true,
                "TreePath": "\ISP Accounts",
                "TotalPasswords": 23,
                "GeneratorName": "Default Password Generator",
                "PolicyName": "SQL Server Policy",
                "PasswordResetEnabled": false,           
                "ForcePasswordGenerator": false,
                "HidePasswords": false,            
                "ShowGuide": false,
                "EnablePasswordResetSchedule": false,
                "PasswordResetSchedule": "05:30",
                "AddDaysToExpiryDate": 120
            }
        ]
              

    Retrieving all Shared Password Lists

    GET /api/passwordlists

    You can retrieve a list of all Shared Password Lists by using the System Wide API Key and a simple GET request.

        # curl Request
        curl https://passwordstate/api/passwordlists/?apikey=<value>
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "PasswordListID": 27,
                "PasswordList": "Web Site's",
                "Description": "Various web sites on the net",
                "ImageFileName": "internet.png",
                "Guide": "",
                "AllowExport": true,
                "PrivatePasswordList": false,
                "TimeBasedAccessRequired": false,
                "HandshakeApprovalRequired": false,
                "PasswordStrengthPolicyID": 7,
                "PasswordGeneratorID": 1,
                "CodePage": "Unicode (UTF-8)",
                "PreventPasswordReuse": 5,
                "AuthenticationType": "None Required",
                "AuthenticationPerSession": false,
                "PreventExpiryDateModification": false,
                "SetExpiryDate": 0,
                "ResetExpiryDate": 0,
                "PreventDragDrop": true,
                "PreventBadPasswordUse": true,
                "ProvideAccessReason": true,
                "TreePath": "\ISP Accounts",
                "TotalPasswords": 23,
                "GeneratorName": "Default Password Generator",
                "PolicyName": "SQL Server Policy",
                "PasswordResetEnabled": false,           
                "ForcePasswordGenerator": false,
                "HidePasswords": false,            
                "ShowGuide": false,
                "EnablePasswordResetSchedule": false,
                "PasswordResetSchedule": "05:30",
                "AddDaysToExpiryDate": 120
            },
            {
                ...
            },
            {
                ...
            }
        ]
              

    Search for Password Lists

    GET /api/searchpasswordlists

    Searching for Password Lists can be achieved via multiple criteria, as outlined by the fields below. You can search using just one field, or multiple to further narrow down the search results. In order to search for Password Lists, you must specify the System Wide API Key which can be found on the screen Administration -> System Settings -> API Keys tab.

    • PasswordList
    • Description
    • TreePath

        # Search by Password List Name
        curl https://passwordstate/api/searchpasswordlists/?PasswordList=<value>&apikey=<value>
                                    
        # Search by Description 
        curl https://passwordstate/api/searchpasswordlists/?Description=<value>&apikey=<value>
        
        # Search by TreePath
        curl https://passwordstate/api/searchpasswordlists/?TreePath=<value>&apikey=<value>
    
        
    The following example shows, in PowerShell, shows how to search by Password List Name, and speciying the API Key in the Header Request.
        # Powershell Request (GET)
        $PasswordstateURL = 'https://passwordstate/api/searchpasswordlists/?PasswordList=<value>'
        $result = Invoke-Restmethod -Method GET -Uri $PasswordstateURL -Header @{ "APIKey" = "<value>" }
        Write-Output $result
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "PasswordListID": 27,
                "PasswordList": "Web Site's",
                "Description": "Various web sites on the net",
                "ImageFileName": "internet.png",
                "Guide": "",
                "AllowExport": true,
                "PrivatePasswordList": false,
                "TimeBasedAccessRequired": false,
                "HandshakeApprovalRequired": false,
                "PasswordStrengthPolicyID": 7,
                "PasswordGeneratorID": 1,
                "CodePage": "Unicode (UTF-8)",
                "PreventPasswordReuse": 5,
                "AuthenticationType": "None Required",
                "AuthenticationPerSession": false,
                "PreventExpiryDateModification": false,
                "SetExpiryDate": 0,
                "ResetExpiryDate": 0,
                "PreventDragDrop": true,
                "PreventBadPasswordUse": true,
                "ProvideAccessReason": true,
                "TreePath": "\ISP Accounts",
                "TotalPasswords": 23,
                "GeneratorName": "Default Password Generator",
                "PolicyName": "SQL Server Policy",
                "PasswordResetEnabled": false,           
                "ForcePasswordGenerator": false,
                "HidePasswords": false,            
                "ShowGuide": false,
                "EnablePasswordResetSchedule": false,
                "PasswordResetSchedule": "05:30",
                "AddDaysToExpiryDate": 120
            }
        ]
        

    Passwords

    A Password object represents an account and associated Password relating to a specific IT System, web site, bank account, etc.

    Here are the accessible fields exposed via the API (note: some of the fields below may be returned as blank depending on which fields are chosen to be used with the associated Password List).

    PasswordID Data Type: Integer
    Description: Unique identifier for the Password object
    Read-only: The time at which the Password object was created.
    Title Data Type: String (255)
    Description: A title to describe the nature of the Password object
    Domain Data Type: String (50)
    Description: If the password relates to an Active Directory Account, then this record will show the NetBIOS value for the domain
    HostName Data Type: String (200)
    Description: If the password relates to an account used on a Host, then this record will show the HostName value for the Host.
    UserName Data Type: String (255)
    Description: Some systems require a username and password to authenticate. This field represents the UserName to do so.
    Description Data Type: String (255)
    Description: A longer verbose description of the nature of the Password object
    GenericField1 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField2 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField3 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField4 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField5 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField6 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField7 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField8 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField9 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    GenericField10 Data Type: String (NA)
    Description: A generic string field which can be renamed to a different value when being displayed in the Passwordstate web interface.
    Note : Generic Fields can be configured as different Field Types, so ensure you pass a valid value for text fields, Select Lists, Radio Buttons or Date Fields.
    AccountTypeID Data Type: Integer
    Description: The ID value representing the Account Type image (derived from the AccountTypes table). An AccountTypeID of 0 (zero) means there is no associated Account Type image for this Password.
    Notes Data Type: String (8000)
    Description: A generic Notes field where additional descriptive text can be added, including HTML formatting.
    URL Data Type: String (255)
    Description: Where you can specify the URL for HTTP, HTTPS, FTP, SFTP, etc.
    Password Data Type: String (stored as encrypted binary field in database)
    Description: The actual password itself for the Password object.
    ExpiryDate Data Type: Date
    Description: The date in which the password value should be reset for this Password object. The date will be displayed in the format specified for the System Setting option 'Default Locale', through the Passwordstate web site interface.
    AllowExport Data Type: Boolean
    Description: Indicates whether this Password object will be exported when the entire Password List contents are exported.
    AccountType Data Type: String (50)
    Description: The name of the Account Type if one has been chosen for the Password record.

    Retrieving a Password

    GET /api/passwords

    You can retrieve an existing Password object using its ID value, and the APIKey of its associated Password List, with a simple GET request.

        # curl Request
        curl https://passwordstate/api/passwords/<PasswordID>?apikey=<value>
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "PasswordID": 46411,
                "Title": "forum4",
                "Domain": "",
                "HostName": "",
                "UserName": "login2",
                "Description": "My login to forum4",
                "GenericField1": "loginasa",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "http://www.microsoft.com",
                "Password": "ZHn#3+A^yc",
                "ExpiryDate": "23/08/2012",
                "AllowExport": true,
                "AccountType": ""
            }
        ]
              

    Updating an Existing Password

    PUT /api/passwords

    An existing Password object can be updated by making a PUT request on the URL, with appropriate fields forming the HTTP message body. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged. When using this method, it is best to specify only those fields you wish to change.

     Note 1: If this password has any associated Password Reset Tasks, they will be queued an executed by the Passwordstate Windows Service - please see output details below for Queued Password Reset Tasks.

     Note 2: If you need to specify the AccountTypeID values, you can go to the screen Administration -> Images and Account Types, and click on the 'Toggle ID Column Visibility' button to determine the appropriate value.

    This method returns the complete updated Password object, as described above.

        # curl Request
        curl --request PUT https://passwordstate/api/passwords 
           -d "PasswordID=46411" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c" \
           -d "password=JENN-ZHn#3+A^yc"
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "PasswordID": 46411,
                "Title": "forum4",
                "UserName": "login2",
                "Description": "My login to forum4",
                "GenericField1": "loginasa",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "http://www.microsoft.com",
                "Password": "JENN-ZHn#3+A^yc",
                "ExpiryDate": "23/08/2012",
                "AllowExport": true,
                "AccountType": ""
            }
        ]
        

     Note: If the password record being updated is 'Managed', in that it is enabled to perform password resets, then the HTTP Reponse will not return the full password object, as no data will change for the record until processed from the Password Resets Queue. Instead, the following will be returned:
       
        # Response
        HTTP/1.1 200           
        [
            {
                "PasswordID": 46411,
                "Status": "Password Queued for Reset(s). Check auditing data, or UI for results.",
                "CurrentPassword": "StenS-Lun#3$2^yc",
                "NewPassword": "JENN-ZHn#3+A^yc"
            }
        ]
        
    In addition to updating fields for the Password objects, there are also a few options which can be used to perform certain actions:
    GeneratePassword Data Type: Boolean
    Description: If set to true, a newly generated random password will be created based on the Password Generator options associated with the Password List. If the Password List is set to use the user's Password Generator options, the Default Password Generator options will be used instead.
    GenerateGenFieldPassword Data Type: Boolean
    Description: If set to true, any 'Generic Fields' which you have set to be of type 'Password' will have a newly generated random password assigned to it. If the Password List or Generic Field is set to use the user's Password Generator options, the Default Password Generator options will be used instead.
    PasswordResetEnabled Data Type: Boolean
    Description: This option will enable the account to perform Password Resets. To do this, the Password List the password record belongs to, must also have this option set.
    EnablePasswordResetSchedule Data Type: Boolean
    Description: If you want to specify a regular scheduled for automatically resetting the value of the Password, you need to enable this option.
    PasswordResetSchedule Data Type: String
    Description: This field allows you to set the schedule for automatic password changes. Specify values in the format of 23:10, or 04:00, etc.
    AddDaysToExpiryDate Data Type: Integer
    Description: Once the password has been changed due to a scheduled reset, you can add an additional (x) number of days to the ExpiryDate field so another reset will occur again in 30, 60, 90 days, etc.
    ScriptID Data Type: Integer
    Description: Most accounts require a Password Reset Script to be assigned to them, with the only exception being Active Directory Accounts - not to specify this field for AD Accounts. To look up the values of the ScriptID's, this can be done by using the 'Toggle ID Column Visibility' button on the Password Reset Scripts screens in Passwordstate.
    PrivilegedAccountID Data Type: Integer
    Description: Some Password Reset Scripts also require a Privileged Account Credential to be associated with the Password record, to initiate connection and perform the reset. Requirements for Privileged Accounts are documented in the User Manual, under the KB Article section. To look up the value of PrivilgedAccountID's, this can be done on the screen Administration -> Privileged Account Credentials.
    HeartbeatEnabled Data Type: Boolean
    Description: If you want to enable the record to perform regular account heartbeat status update, then set this field to True.
    HeartbeatSchedule Data Type: String
    Description: This field allows you to set the schedule for the account heartbeat status update. Specify values in the format of 23:10, or 04:00, etc.
    ValidationScriptID Data Type: Integer
    Description: When enabling Account Heartbeat, you must associate the correct Password Validation Script to the record (all account types require a Validation Script to be selected). To look up the values of the ValidationScriptID's, this can be done by using the 'Toggle ID Column Visibility' button on the Password Validation Scripts screens in Passwordstate.
    HostName Data Type: String
    Description: If the record relates to account on a Host, then you must specify the Host Name here, as it is stored on the Hosts screen in Passwordstate.
    ADDomainNetBIOS Data Type: String
    Description: If the record relates to an Active Directory account, then you must specify the Active Directory NetBIOS value here, as it is stored on the Administration -> Active Directory Domains screen in Passwordstate.

    Adding a New Password

    POST /api/passwords

    Adding a new Password object can be achieved by making a POST request on the URL, with appropriate fields forming the HTTP message body. Only the fields provided in the data block will be updated; any unspecified fields will be posted as Null values.

    This method returns the new Password object as described above, as well as the URL location in the HTTP Headers where the Password object can be retrieved from.

     Note: You can either specify the AccountType or AccountTypeID if needed when adding password records. Account Types and their ID values can be seen on the screen Administration -> Images and Account Types, and click on the 'Toggle ID Column Visibility' button to determine the appropriate value.

        # curl Request
        curl --request POST https://passwordstate/api/passwords 
           -d "PasswordListID=27" \
           -d "Title=North American Core Router 1" \
           -d "UserName=narouter1" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c" \
           -d "password=StenS-Lun#3$2^yc"
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "PasswordID": 47401,
                "Title": "North American Core Router 1",
                "UserName": "narouter1",
                "Description": "",
                "GenericField1": "",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "",
                "Password": "StenS-Lun#3$2^yc",
                "ExpiryDate": "",
                "AllowExport": true,
                "AccountType": ""
            }
        ]
        
    In addition to specifying each of the fields manually for the Password object, there are also a couple of options which can be used to perform certain actions:
    GeneratePassword Data Type: Boolean
    Description: If set to true, a newly generated random password will be created based on the Password Generator options associated with the Password List. If the Password List is set to use the user's Password Generator options, the Default Password Generator options will be used instead.
    GenerateGenFieldPassword Data Type: Boolean
    Description: If set to true, any 'Generic Fields' which you have set to be of type 'Password' will have a newly generated random password assigned to it. If the Password List or Generic Field is set to use the user's Password Generator options, the Default Password Generator options will be used instead.
    PasswordResetEnabled Data Type: Boolean
    Description: This option will enable the account to perform Password Resets. To do this, the Password List the password record belongs to, must also have this option set.
    EnablePasswordResetSchedule Data Type: Boolean
    Description: If you want to specify a regular scheduled for automatically resetting the value of the Password, you need to enable this option.
    PasswordResetSchedule Data Type: String
    Description: This field allows you to set the schedule for automatic password changes. Specify values in the format of 23:10, or 04:00, etc.
    AddDaysToExpiryDate Data Type: Integer
    Description: Once the password has been changed due to a scheduled reset, you can add an additional (x) number of days to the ExpiryDate field so another reset will occur again in 30, 60, 90 days, etc.
    ScriptID Data Type: Integer
    Description: Most accounts require a Password Reset Script to be assigned to them, with the only exception being Active Directory Accounts - not to specify this field for AD Accounts. To look up the values of the ScriptID's, this can be done by using the 'Toggle ID Column Visibility' button on the Password Reset Scripts screens in Passwordstate.
    PrivilegedAccountID Data Type: Integer
    Description: Some Password Reset Scripts also require a Privileged Account Credential to be associated with the Password record, to initiate connection and perform the reset. Requirements for Privileged Accounts are documented in the User Manual, under the KB Article section. To look up the value of PrivilgedAccountID's, this can be done on the screen Administration -> Privileged Account Credentials.
    HeartbeatEnabled Data Type: Boolean
    Description: If you want to enable the record to perform regular account heartbeat status update, then set this field to True.
    HeartbeatSchedule Data Type: String
    Description: This field allows you to set the schedule for the account heartbeat status update. Specify values in the format of 23:10, or 04:00, etc.
    ValidationScriptID Data Type: Integer
    Description: When enabling Account Heartbeat, you must associate the correct Password Validation Script to the record (all account types require a Validation Script to be selected). To look up the values of the ValidationScriptID's, this can be done by using the 'Toggle ID Column Visibility' button on the Password Validation Scripts screens in Passwordstate.
    HostName Data Type: String
    Description: If the record relates to account on a Host, then you must specify the Host Name here, as it is stored on the Hosts screen in Passwordstate.
    ADDomainNetBIOS Data Type: String
    Description: If the record relates to an Active Directory account, then you must specify the Active Directory NetBIOS value here, as it is stored on the Administration -> Active Directory Domains screen in Passwordstate.

    Adding a New Password Reset Dependency

    POST /api/dependencies

    When an account is enabled to perform Password Resets, it possible to have 'dependant' tasks which can also be executed at the same time the password is reset. Examples of this are where Active Directory accounts are being used for Windows Services, Scheduled Tasks and IIS Application Pools. You can also add a dependant reset task which does not relate to these types of Windows resources i.e. you can execute any custom PowerShell script you want.

    This method returns the new Dependency object as described below.

     Note: HostName is an optional field, and only needs to be specified if the dependant task needs to be executed on a specific Host.

        # curl Request
        curl --request POST https://passwordstate/api/dependencies 
           -d "DependencyType=Windows Service" \
           -d "DependencyName=Custom Windows Service" \
           -d "HostName=win2k12server78.domain.local" \
           -d "PasswordID=1874" \
           -d "ScriptID=17" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c"
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "TaskID": 57,
                "DependencyType": "Windows Service",
                "DependencyName": "Custom Windows Service",
                "HostName": "win2k12server78.domain.local",
                "PasswordID": "1874",
                "ScriptID": "17"
            }
        ]
        
    Below is a description of each of the parameters for this API Method:
    DependencyType Data Type: String
    Description: DependencyType relates to Windows type resources. Possible values are Windows Service, IIS Application Pool, Scheduled Tasks and COM+ Component.
    DependencyName Data Type: String
    Description: The actual name of the Dependency, as it relates to Windows resources i.e. the name of a Windows Service, or Scheduled Task.
    HostName Data Type: String
    Description: If this dependant task is to be executed against a specific Host, then you specify the name of the Host here - it must match the name of the Host as it is recorded in Passwordstate. If this dependant task is not to be executed against a specific Host, then this field can be omitted.
    PasswordID Data Type: Integer
    Description: The PasswordID value of the password record in Passwordstate.
    ScriptID Data Type: Integer
    Description: The ScriptID value of the dependant script which will be executed, once the Password record has finished executing its own password reset task.

    Deleting a Password

    DELETE /api/passwords

    Deleting a Password is possible by submitting a 'DELETE' HTTP Verb to the API. When a Password is deleted, you will be returned a Http Status Code 04 204 - NoContent.

    You can choose to either move the Password to the Recycle Bin, or perform a permanent delete by specifying the appropriate value for the MoveToRecycleBin parameter (True or False).

        # curl Request
        curl --request DELETE "https://passwordstate/api/passwords/<PasswordID>?APIKey=<value>&MoveToRecycleBin=<value>
        
       
        # Response
        HTTP/1.1 204 No Content           
        
        

    Retrieving Password History

    GET /api/passwordhistory

    You can retrieve all the history for a Password object by specifying the PasswordID & APIKey values, with a simple GET request.

    In addition to the standard fields for a Password object, there are a few more which need to be explained:

    PasswordHistoryID Data Type: Integer
    Description: Unique identifier for the Password History object
    DateChanged Data Type: DateTime
    Description: The date and time the Password object was updated, and the Password History record added.
    PasswordList Data Type: String
    Description: The name of the Password List the history records belongs to.
    UserID Data Type: String
    Description: The UserID of the user who made the change to the Password object. This UserID will also show the value of 'WebAPI' if the Password was updated via the API.
    FirstName Data Type: String
    Description: The First Name of the user who made the change to the Password object.
    Surname Data Type: String
    Description: The Surname of the user who made the change to the Password object.
        # curl Request
        curl https://passwordstate/api/passwordhistory/<PasswordID>?apikey=<value>
        
       
        # Response
        [
            {
                "PasswordHistoryID": 6319,
                "Title": "forum4_counter3",
                "UserName": "login2",
                "Description": "My login to forum4",
                "GenericField1": "loginasa",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "http://www.microsoft.com",
                "Password": "gin-hid-bud-9uXmoJzgdHNp",
                "ExpiryDate": "15/01/2013",
                "DateChanged": "15/01/2013 12:29:07 PM",
                "PasswordList": "Web Site's",
                "UserID": "halox\msand",
                "FirstName": "Mark",
                "Surname": "Sandford",
                "PasswordID": 46411,
                "AccountType": ""
            },
            {
                "PasswordHistoryID": 6318,
                "Title": "forum4_counter3",
                "UserName": "login2",
                "Description": "My login to forum4",
                "GenericField1": "loginasa",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "http://www.microsoft.com",
                "Password": "bye-be-ere-RnQ19LWuAwSyJh",
                "ExpiryDate": "15/01/2013",
                "DateChanged": "15/01/2013 12:28:48 PM",
                "PasswordList": "Web Site's",
                "UserID": "WebAPI",
                "FirstName": "Passwordstate",
                "Surname": "Web API",
                "PasswordID": 46411,
                "AccountType": ""
            },
            ...
        ]
              

    Retrieving all Passwords in a Password List

    GET /api/passwords

    You can retrieve all Passwords in a Password List by specifying the PasswordListID & APIKey values, with a simple GET request.

     Note 1: If you omit the 'QueryAll' parameter, the API will interpret the PasswordListID as PasswordID, due to the syntax of the API Controller.

     Note 2: If the Password field value is visible in the results of this API call, it will add one audit record for every password retrieved. By setting the parameter ExludePassword to true, it will return all fields as normal, except the Password field will be blank, and no Audit records will be added. If the ExcludePassword parameter is omitted, the default option is false.

     Note 3: By default, the retrieval of all Passwords records will add one Audit record for every Password record returned. If you wish to prevent audit records from being added, you can set the PreventAuditing parameter to true - if this parameter is omitted, the default option is false.

        # curl Request
        curl https://passwordstate/api/passwords/<PasswordListID>?apikey=<value>&QueryAll&ExcludePassword=<value> _
                     &PreventAuditing=<value>
        
       
        # Response
        [
            {
                "PasswordID": 46865,
                "Title": "$25 Winners",
                "UserName": "",
                "Description": "Must be for a pool",
                "GenericField1": "",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "",
                "Password": "q6xnfuW&B",
                "ExpiryDate": "",
                "AllowExport": true,
                "AccountType": ""
                },
            {
                "PasswordID": 46903,
                "Title": "atelerik",
                "UserName": "useraccount1",
                "Description": "Terlerik Login",
                "GenericField1": "",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "http://www.telerik.com",
                "Password": "ZHn#3+A^yc",
                "ExpiryDate": "",
                "AllowExport": true,
                "AccountType": ""
            },
            ...
        ]
              

    Retrieving all Passwords in all Password Lists

    GET /api/passwords

    You can retrieve all Passwords in all Shared Password Lists by specifying the System Wide API Key, with a simple GET request - this is similar to the 'Export All Passwords' feature available in the Administration area of the Passwordstate web site.

     Note: By default, the retrieval of all Passwords records will add one Audit record for every Password record returned. If you wish to prevent audit records from being added, you can set the PreventAuditing parameter to true - if this parameter is omitted, the default option is false.

        # curl Request
        curl https://passwordstate/api/passwords/?apikey=<value>&QueryAll&PreventAuditing=<value>
        
       
        # Response
        [
            {
                "PasswordListID": 197,
                "PasswordList": "Web Sites",
                "TreePath": "\Customers\CustomerA",
                "PasswordID": 46865,
                "Title": "$25 Winners",
                "UserName": "",
                "Description": "Must be for a pool",
                "GenericField1": "",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "",
                "Password": "q6xnfuW&B",
                "ExpiryDate": "",
                "AllowExport": true
                },
            {
                "PasswordListID": 197,
                "PasswordList": "Web Sites",
                "TreePath": "\Customers\CustomerA",
                "PasswordID": 46903,
                "Title": "atelerik",
                "UserName": "useraccount1",
                "Description": "Terlerik Login",
                "GenericField1": "",
                "GenericField2": "",
                "GenericField3": "",
                "GenericField4": "",
                "GenericField5": "",
                "GenericField6": "",
                "GenericField7": "",
                "GenericField8": "",
                "GenericField9": "",
                "GenericField10": "",
                "AccountTypeID": 0,
                "Notes": "",
                "URL": "http://www.telerik.com",
                "Password": "ZHn#3+A^yc",
                "ExpiryDate": "",
                "AllowExport": true
            },
            ...
        ]
              

    Searching for Passwords

    GET /api/searchpasswords

    There are two ways in which you can search for Passwords via the API, and you can search just within a single Password List, or across all Shared Passwords Lists - searching across all Shared Passwords Lists requires you to specify the System Settings API Key. The two search methods are:

    • Via a General Search across the majority of fields in the Passwords table
    • Via Specific Search criteria, based on fields and values you specify in the URL


     Note 1: You can perform an exact match search by enclosing your search criteria in double quotes i.e. "root_admin"

     Note 2: If the Password field value is visible in the results of this API call, it will add one audit record for every password retrieved. By setting the parameter ExludePassword to true, it will return all fields as normal, except the Password field will be blank, and no Audit records will be added. If the ExcludePassword parameter is omitted, the default option is false.

     Note 3: By default, the retrieval of all Passwords records will add one Audit record for every Password record returned. If you wish to prevent audit records from being added, you can set the PreventAuditing parameter to true - if this parameter is omitted, the default option is false.

        # General Search by Password List
        curl https://passwordstate/api/searchpasswords/<PasswordListID>?search=<value>&apikey=<value>&ExcludePassword=<value> _
                     &PreventAuditing=<value>
                                    
        # General Search across all Password Lists and all Fields (must use System Wide API Key) 
        curl https://passwordstate/api/searchpasswords/?search=<value>&apikey=<value>&ExcludePassword=<value> _
                     &PreventAuditing=<value>
        
        # Specific Search, by 'Title', within a Password List
        curl https://passwordstate/api/searchpasswords/<PasswordListID>?title=<value>&apikey=<value>&ExcludePassword=<value> _
                     &PreventAuditing=<value>
        
        # Specific Search, by 'UserName', within a Password List
        curl https://passwordstate/api/searchpasswords/<PasswordListID>?username=<value>&apikey=<value>&ExcludePassword=<value> _
                     &PreventAuditing=<value>
        
        # Specific Search, by 'Title' and 'UserName', across all Password Lists (must use System Wide API Key)
        curl https://passwordstate/api/searchpasswords/?title=<value>&username=<value>&apikey=<value>&ExcludePassword=<value> _
                     &PreventAuditing=<value>
        

    'General Search' Instructions

    When performing a General Search, it will query the Passwords table for fields which Contain the value you specify for the Search= parameter. The fields which will be searched are:
    • Title
    • ADDomainNetBIOS
    • HostName
    • UserName
    • AccountType
    • Description
    • GenericField1
    • GenericField2
    • GenericField3
    • GenericField4
    • GenericField5
    • GenericField6
    • GenericField7
    • GenericField8
    • GenericField9
    • GenericField10
    • Notes
    • URL

    'Specific Search' Instructions

    When performing a Specific Search, it will query the Passwords table based on one or more of the parameters you specify in the URL. The fields which can be searched are:
    • Title
    • HostName
    • ADDomainNetBIOS
    • UserName
    • AccountTypeID
    • AccountType
    • Description
    • GenericField1
    • GenericField2
    • GenericField3
    • GenericField4
    • GenericField5
    • GenericField6
    • GenericField7
    • GenericField8
    • GenericField9
    • GenericField10
    • Notes
    • URL
    • PasswordResetEnabled
    • ExpiryDate
    • ExpiryDateRange
    • AndOr

    ExpiryDate Searching Explained

    When performing a Specific Search by the ExpiryDate field, it will perform an exact match on this value. If you wish to query based on a date range, then omit this parameter and use the ExpiryDateRange parameter instead.

    Note: Dates must be supplied in the ISO 8601 international standard for date format of YYYY-MM-DD.

    ExpiryDateRange Searching Explained

    It is possible to specify SQL style query syntax for the ExpiryDateRange parameter, so you can construct a query based on date ranges if needed. Examples of the query syntax you can use is (ensure you separate two dates with a single comma):

    • ExpiryDateRange=ExpiryDate>=2012-07-06,ExpiryDate<=2013-01-01
    • ExpiryDateRange=ExpiryDate>2012-01-01,ExpiryDate<=2012-02-28
    • ExpiryDateRange=ExpiryDate>2013-01-01
    • ExpiryDateRange=ExpiryDate<=2012-11-30

    Note: Dates must be supplied in the ISO 8601 international standard for date format of YYYY-MM-DD.

    AndOr Operator Explained

    As you can build up your query string based on one or more fields, you can also specify how these queries are joined in the SQL query - either using the OR operator, or the AND operator. If you omit this parameter from the URL, OR will be used.

    As you'd expect, using the OR operator will return a greater number of results, while the AND operator will return less results as it is a more specific type of query.

    Final Search Notes

    As you are passing parameters via the URL, it's possible you may wish to query based on characters which normally form part of the normalQuery Stringsyntax. If this is the case, then you may not toURL Encodeparts of your search criteria. An example of this would be:

    The ampersand character of & - you would instead need to represent this as %26

    Hosts

    Multiple methods are available with the API to query for Hosts which are already added to Passwordstate, or to add new Host records, or delete existing Host records.

    Host records in Passwordstate are primarily used for facilitating Passwords resets on various Host types, and also for the Remote Session Launcher utility.

    HostName Data Type: String
    Description: The name of the Host - FQDN host names are preferred if possible
    HostType Data Type: String (50)
    Description: A Host Type which describes the Host i.e. Windows, Linux, Switch, Router, etc. A list of Host Types can be found on the screen Administration -> Host Types and Operating Systems
    OperatingSystem Data Type: String (50)
    Description: The type of Operating System the Host is using. A list of Operting Systems can be found on the screen Administration -> Host Types and Operating Systems
    SQLServer Data Type: Boolean
    Description: Indicates if the Host has Microsoft SQL Server installed on it.
    SQLInstanceName Data Type: String (100)
    Description: Indicates either the Microsoft SQL Server Instance Name, or Oracle Service Name.
    MySQLServer Data Type: Boolean
    Description: Indicates if the Host has MySQL Server installed on it.
    OracleServer Data Type: Boolean
    Description: Indicates if the Host has Oracle Database Server installed on it.
    DatabasePortNumber Data Type: Integer
    Description: Indicates the Port Number the database server is accessible on. Leaving the Port Number blank is most cases should work, but you can specify non-standard port numbers if required
    RemoteConnectionType Data Type: String (50)
    Description: The type of Remote Connection Protocol for the server i.e. RDP, SSH, Telnet or VNC.
    RemoteConnectionPortNumber Data Type: Integer
    Description: The Port Number used for the Remote Connection type. Default Port Numbers are RDP: 3389, SSHL 22, Telnet: 23 and VNC: 5901.
    RemoteConnectionParameters Data Type: String (500)
    Description: If the required Remote Session Client requires additional parameters to be specified to connect to the remote Host, they can be specified using this field.

    Searching for Hosts

    GET /api/hosts

    Searching for Hosts can be achieved via multiple criteria, as outlined by the fields below. You can search using just one field, or multiple to further narrow down the search results. In order to search for Hosts, you must specify the Hosts API Key which can be found on the screen Administration -> System Settings -> API Keys tab.

    • HostName
    • HostType
    • OperatingSystem
    • SQLServer
    • MySQLServer
    • OracleServer

        # Search by Host Name
        curl https://passwordstate/api/hosts/?HostName=<value>&apikey=<value>
                                    
        # Search by Host Name and Operating System 
        curl https://passwordstate/api/hosts/?HostName=<value>&OperatingSystem=<value>&apikey=<value>
        
        # Search by Host Name, Operating System and SQL Server
        curl https://passwordstate/api/hosts/?HostName=<value>&OperatingSystem=<value>&SQLServer=True&apikey=<value>
        
        # Searching for all SQL Servers
        curl https://passwordstate/api/hosts/?SQLServer=True&apikey=<value>
    
        # Searching for all Window 2012 Servers
        curl https://passwordstate/api/hosts/?OperatingSystem=Windows Server 2012&apikey=<value>
        
    The following example shows, in PowerShell, shows how to search by Host Name and Operating System, and speciying the API Key in the Header Request.
        # Powershell Request (GET)
        $PasswordstateURL = 'https://passwordstate/api/hosts/?HostName=<value>&OperatingSystem=<value>'
        $result = Invoke-Restmethod -Method GET -Uri $PasswordstateURL -Header @{ "APIKey" = "<value>" }
        Write-Output $result
    
       
        # Response
        HTTP/1.1 200           
        [
            {
    
                "HostID":12345,
                "HostName":"abcserver.halox.net",
                "HostType":"Windows",
                "OperatingSystem":"Windows Server 2012",
                "SQLServer":false,
                "SQLInstanceName":"",
                "MySQLServer":false,
                "OracleServer":false,
                "DatabasePortNumber":"",
                "RemoteConnectionType":"RDP",
                "RemoteConnectionPortNumber":"3389",	
                "RemoteConnectionParameters":"",
                "Tag":"MyServer"
            }
        ]
    

    Add a New Host

    POST /api/hosts

    Adding a new Host object can be achieved by making a POST request on the URL, with appropriate fields forming the HTTP message body. To create Hosts, you must use the System Wide Hosts API Key.

    The curl example below creates a Host record with the bare minimum amount of fields to be specified.

        # curl Request
        curl --request POST https://passwordstate/api/hosts
           -d "HostName=abcserver.halox.net" \
           -d "HostType=Windows" \
           -d "OperatingSystem=Windows Server 2012" \
           -d "APIKey=<value>"
        

    The PowerShell example below creates a Host record more fields specified.

    Note: The \ after -ContentType is to indicate a line break so the code is displayed correctly on this page.

         # PowerShell Request
            $jsonData = '
            {
    	        "HostName":"abcserver.halox.net",
    	        "HostType":"Windows",
    	        "OperatingSystem":"Windows Server 2012",
    	        "SQLServer":false,
    	        "SQLInstanceName":"",
    	        "MySQLServer":false,
    	        "OracleServer":false,
    	        "DatabasePortNumber":"",
    	        "RemoteConnectionType":"RDP",
    	        "RemoteConnectionPortNumber":"3389",	
    	        "RemoteConnectionParameters":"",
    	        "Tag":"MyServer"
            }
            '
            $PasswordstateURL = 'https://passwordstate/api'
            $result = Invoke-Restmethod -Method Post -Uri $PasswordstateURL'/hosts' -ContentType "application/json" \
                                        -Body $jsonData -Header @{ "APIKey" = "<value>" }
            Write-Output $result
        

    Delete a New Host

    DELETE /api/hosts

    Deleting a Host is possible by submitting a 'DELETE' HTTP Verb to the API. When a Host is deleted, you will be returned a Http Status Code 04 204 - NoContent.

        # curl Request
        curl --request DELETE "https://passwordstate/api/hosts/<HostName>
    
        # PowerShell Request
        $PasswordstateURL = 'https://passwordstate/api/hosts/<HostName>'
        Invoke-Restmethod -Method Delete -Uri $PasswordstateURL -Header @{ "APIKey" = "<Value>" }
        
       
        # Response
        HTTP/1.1 204 No Content           
        
        

    Documents

    It possible to Add and retrieve both documents linked to individual password records, or linked to entire Password Lists.

    Documents will be retrieved via the System.Net.HTTP.HttpResponseMessage .NET Framework class, and it will be up to you how you capture this response message and process it. As an example of how this works, it you were to make the API call from your browser window, the browser will prompt you where to save the document.

    Adding a New Password Document

    POST /api/document/password/

    Uploading a new Password Document can be achieved by making a POST request on the URL, with appropriate fields forming the QueryString of the URL. To upload documents, you must use the API Key from the specific Password List, or the System Wide API Key.

    Note: It's not possible to specify the Document Name and Description in the BODY of the HTTP Post, as this is where the document is uploaded from.

        # curl Request
        curl --request POST "https://passwordstate/api/document/password/<PasswordID>?DocumentName=<DocumentName> _
                &DocumentDescription=<DocumentDescription>" \
           -F "file=@/home/<UserID>/Desktop/<DocumentName>" 
           
    
        # PowerShell Request
        $documentPath = "D:\Build-Specifications.txt"
        $uri = "https://passwordstate/api/document/password/<PasswordID>?DocumentName=<DocumentName> _
                &DocumentDescription=<DocumentDescription>"
        
        $result = Invoke-RestMethod -Uri $uri -Method Post -InFile $documentPath -ContentType 'multipart/form-data' _ 
                                    -Header @{ "APIKey" = "<APIKey>" }
        Write-Host $result
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "DocumentID": 34,
                "DocumentName": "Build-Specifications.txt"
            }
        ]
        

    Adding a New Password List Document

    POST /api/document/passwordlist/

    Uploading a new Password List Document can be achieved by making a POST request on the URL, with appropriate fields forming the QueryString of the URL. To upload documents, you must use the API Key from the specific Password List, or the System Wide API Key.

    Note: It's not possible to specify the Document Name and Description in the BODY of the HTTP Post, as this is where the document is uploaded from.

        # curl Request
        curl --request POST "https://passwordstate/api/document/passwordlist/<PasswordListID>?DocumentName=<DocumentName> _
                &DocumentDescription=<DocumentDescription>" \ 
           -F "file=@/home/<UserID>/Desktop/<DocumentName>"
           
    
        # PowerShell Request
        $documentPath = "D:\Build-Specifications.txt"
        $uri = "https://passwordstate/api/document/passwordlist/<PasswordListID>?DocumentName=<DocumentName> _
                &DocumentDescription=<DocumentDescription>"
        
        $result = Invoke-RestMethod -Uri $uri -Method Post -InFile $documentPath -ContentType 'multipart/form-data' _ 
                                    -Header @{ "APIKey" = "<APIKey>" }
        Write-Host $result
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "DocumentID": 126,
                "DocumentName": "Build-Specifications.txt"
            }
        ]
        

    Retrieving Password Documents

    GET /api/document/password

    Retrieving a document can be achieved by passing a GET request with the DocumentID and appropriate API Key.

        # curl Request
        curl https://passwordstate/api/document/password/<documentid>?apikey=<value>
        

    Retrieving Password List Documents

    GET /api/document/passwordlist

    Retrieving a document can be achieved by passing a GET request with the DocumentID and appropriate API Key.

        # curl Request
        curl https://passwordstate/api/document/passwordlist/<documentid>?apikey=<value>
        

    Generate Random Passwords

    You can generate one or more random Passwords from the API, either by specifying the settings manually, or by passing the PasswordGeneratorID value of one of the Password Generator options defined within Passwordstate.

    There is only one field exposed via the API when generating a password, and it is the Password field itself.

    Password Data Type: String
    Description: Randomly generated Password value.

    Generating the Password

    GET /api/generatepassword

    Manual Password Generator Options Explained

    When generating a random Password, you can either use the settings based as on of the saved 'Password Generator' options in Passwordstate, or you can specify all the settings manually. To specify the settings manually, you will need to understand what each of the parameters are intended for.

    IncludeAlphaSpecial Data Type: Boolean
    Description: Include Alphanumerics and Special Characters.
    IncludeWordPhrases Data Type: Boolean
    Description: Include Word Phrases - random word will be generated.
    minLength Data Type: Integer
    Description: Minimum length for Alphanumercis and Special Characters.
    maxLength Data Type: Integer
    Description: Maximum length for Alphanumercis and Special Characters.
    lowerCaseChars Data Type: Boolean
    Description: Include lowercase characters.
    upperCaseChars Data Type: Boolean
    Description: Include uppercase characters.
    numericChars Data Type: Boolean
    Description: Include numeric characters.
    higherAlphaRatio Data Type: Boolean
    Description: Include higher ratio of alphanumerics vs special characters.
    ambiguousChars Data Type: Boolean
    Description: Include ambiguous characters - such as I, l, and 1.
    specialChars Data Type: Boolean
    Description: Include special characters.
    specialCharsText Data Type: String
    Description: List of special characters - such as !#$%^&*+/=_-.
    bracketChars Data Type: Boolean
    Description: Include brackets.
    bracketCharsText Data Type: String
    Description: List of brackets - such as [](){}<>.
    NumberOfWords Data Type: Integer
    Description: The number of words to include.
    MaxWordLength Data Type: Integer
    Description: Maximum word length to generate.
    PrefixAppend Data Type: String
    Description: P to Prefix the Word, A to Append and I to Insert.
    SeparateWords Data Type: String
    Description: Separate the generated Words with S for Spaces, D for Dashes and N for No Separation.
    ExcludeChars Data Type: String
    Description: Exclude certain characters and numbers from the newly generated password.
    GeneratePattern Data Type: Boolean
    Description: Generate based on a pattern of upper and lowercase letters, and numbers.
    Pattern Data Type: String
    Description: l for Lowercase, u for uppercase, n for numbers and s for special characters i.e. ullllnnnnssss
    Qty Data Type: Integer
    Description: Generate one or more random passwords
    APIKey Data Type: String
    Description: Password Generator API Key from System Settings screen to authenticate the API request
        # Generate one Password based on the 'Default Password Generator' options
        curl https://passwordstate/api/generatepassword/?apikey=<value>
    
        # Generate one or more Passwords based on the 'Default Password Generator' options
            curl https://passwordstate/api/generatepassword/?Qty=<value>&apikey=<value>
    
        # Generate one Password based on a Password Generator option you specify
            curl https://passwordstate/api/generatepassword/?PasswordGeneratorID=<value>&apikey=<value>
    
        # Generate one or more Passwords based on a Password Generator option you specify
            curl https://passwordstate/api/generatepassword/?PasswordGeneratorID=<value>&Qty=<value>&apikey=<value>
    
        # Generate one Password based on options you specify manually
            curl https://passwordstate/api/generatepassword/?IncludeAlphaSpecial=<value>&IncludeWordPhrases=<value>
            &minLength=<value>&maxLength=<value>&lowerCaseChars=<value>&upperCaseChars=<value>
            &numericChars=<value>&higherAlphaRatio=<value>&ambiguousChars=<value>&specialChars=<value>
            &specialCharsText=<value>&bracketChars=<value>&bracketCharsText=<value>&NumberOfWords=<value>
            &MaxWordLength=<value>&PrefixAppend=<value>&SeparateWords=<value>&ExcludeChars=<value>
            &GeneratePattern=<value>&Pattern=<value>&apikey=<value>
        
        # Generate one or more Passwords based on options you specify manually
            curl https://passwordstate/api/generatepassword/?IncludeAlphaSpecial=<value>&IncludeWordPhrases=<value>
            &minLength=<value>&maxLength=<value>&lowerCaseChars=<value>&upperCaseChars=<value>
            &numericChars=<value>&higherAlphaRatio=<value>&ambiguousChars=<value>&specialChars=<value>
            &specialCharsText=<value>&bracketChars=<value>&bracketCharsText=<value>&NumberOfWords=<value>
            &MaxWordLength=<value>&PrefixAppend=<value>&SeparateWords=<value>&ExcludeChars=<value>
            &GeneratePattern=<value>&Pattern=<value>&Qty=<value>&apikey=<value>
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "Password": "ZHn#3+A^yc",
            }
        ]