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 an Password Lists API key

    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 an System Wide API key

    A unique API key can be created in the 'System Settings' section of Passwordstate, and this powerful API Key can perform actions on Password Lists which do not have an associated API Key.

    Examples of where the System Wide API Key can be used is when you wish to search for a Password record across all Password Lists, or to return all Passwords for all Shared Password Lists - similar to the 'Export All Passwords' feature in the Administration Area of the Passwordstate web site.

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

    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           
        [
            {
                "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,
                "ResetExpiryDate": 0,
                "PreventDragDrop": true,
                "PreventBadPasswordUse": true,
                "ProvideAccessReason": true,
                "TreePath": "\ISP Accounts",
                "TotalPasswords": 23,
                "GeneratorName": "Default Password Generator",
                "PolicyName": "SQL Server Policy"
            }
        ]
              
  3. Errors

    Sadly, 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.
    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.
        # 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 http://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.

  5. Reference

    The following API References details which methods are available to you in retrieving and updating data in Passwordstate. It includes information such has expected HTTP Verbs, URL syntax, Input and Output Parameters, and example data output.
  6. 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 is 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.

    Retrieving a Password List

    GET /api/passwordlists

    You can retrieve an existing Password List using it 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,
                "ResetExpiryDate": 0,
                "PreventDragDrop": true,
                "PreventBadPasswordUse": true,
                "ProvideAccessReason": true,
                "TreePath": "\ISP Accounts",
                "TotalPasswords": 23,
                "GeneratorName": "Default Password Generator",
                "PolicyName": "SQL Server Policy"
            }
        ]
              

    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
    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 configure 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 configure 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 configure 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 configure 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 configure 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 configure 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 configure 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 configure 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 configure 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 configure 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.

    Retrieving a Password

    GET /api/passwords

    You can retrieve an existing Password object using it 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",
                "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
            }
        ]
              

    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.

    This method returns the complete updated Password object, 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
            }
        ]
        
    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.
    ComplianceRetries Data Type: Integer
    Description: Compliance retries is used in conjunction with "GeneratePassword", with the default value being 10 if you omit to include this parameter. As a Password List, and various System Wide Settings, can be configured with certain restrictions (detailed below), if you are generating a new random password then ComplianceRetries is used to attempt to generate another 'compliant' password if the previous attempt failed. If the value of ComplianceRetries is reached, updating the password will fail and send back an appropriate HTTP response.

    1. Check to see if the newly generated passwords conforms to any Bad Password settings
    2. Check to see if the newly generated passwords conforms to any mandatory Password Strength settings
    3. Check to see if the newly generated passwords conforms to any Password Reuse settings

    Note: These type of Password related options above do not apply to any Generic Fields which you have configured to be of type 'Password'.
    SyncWindowsAccount Data Type: Boolean
    Description: If the Password is related to an Active Directory or Windows Server account, and you wish to synchronize the password change with Windows, then this flag can be used.

    Please Note: In order for a synchronization to occur successfully, there are certain criteria which must be met first, which are:

    1. The Password List must have the field 'Account Type' associated with it
    2. The Password List must have one 'Generic Field' associated with it, and it must be named 'Domain or Host'
    3. The Account Type selected for the Password object must be 'Windows'
        # curl Request
        curl --request PUT https://passwordstate/api/passwords
           -d "PasswordID=46411" \
           -d "apikey=b2a57c34fe96d8f36a89c25eb47d4b6c" \
           -d "GeneratePassword=true" \
           -d "ComplianceRetries=20" \
           -d "SyncWindowsAccount=true"
        

    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.

        # 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
            }
        ]
        
    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.
    ComplianceRetries Data Type: Integer
    Description: Compliance retries is used in conjunction with "GeneratePassword", with the default value being 10 if you omit to include this parameter. As a Password List, and various System Wide Settings, can be configured with certain restrictions (detailed below), if you are generating a new random password then ComplianceRetries is used to attempt to generate another 'compliant' password if the previous attempt failed. If the value of ComplianceRetries is reached, updating the password will fail and send back an appropriate HTTP response.

    1. Check to see if the newly generated passwords conforms to any Bad Password settings
    2. Check to see if the newly generated passwords conforms to any mandatory Password Strength settings
    3. Check to see if the newly generated passwords conforms to any Password Reuse settings

    Note: These type of Password related options above do not apply to any Generic Fields which you have configured to be of type 'Password'.
        # 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 "GeneratePassword=true" \
           -d "ComplianceRetries=20"
        

    Retrieving Password History

    GET /api/password

    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
            },
            {
                "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
            },
    
            ...
    
        ]
              

    Retrieving all Passwords in a Password List

    GET /api/passwords

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

     Note: This API call will add one audit record for every password retrieved
     Note: If you omit the 'QueryAll' parameter, the API will interpret the PasswordListID as PasswordID, due to the syntax of the API Controller.

        # curl Request
        curl https://passwordstate/api/passwords/<PasswordListID>?apikey=<value>&QueryAll
        
       
        # 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
                },
            {
                "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
            },
    
            ...
    
        ]
              

    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: This API call will add one audit record for every password retrieved.

        # curl Request
        curl https://passwordstate/api/passwords/?apikey=<value>&QueryAll
        
       
        # 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


        # General Search by Password List
        curl https://passwordstate/api/searchpasswords/<PasswordListID>?search=<value>&apikey=<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>
    
        # Specific Search, by 'Title', within a Password List
        curl https://passwordstate/api/searchpasswords/<PasswordListID>?title=<value>&apikey=<value>
    
        # Specific Search, by 'Username', within a Password List
        curl https://passwordstate/api/searchpasswords/<PasswordListID>?username=<value>&apikey=<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>
        

    '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
    • Username
    • 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
    • Username
    • Description
    • GenericField1
    • GenericField2
    • GenericField3
    • GenericField4
    • GenericField5
    • GenericField6
    • GenericField7
    • GenericField8
    • GenericField9
    • GenericField10
    • Notes
    • URL
    • 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 theISO 8601international 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 theISO 8601international 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

    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.
        # Generate one Password based on the 'Default Password Generator' options
        curl https://passwordstate/api/generatepassword
    
        # Generate one or more Passwords based on the 'Default Password Generator' options
        curl https://passwordstate/api/generatepassword/?Qty=<value>
    
        # Generate one Password based on a Password Generator option you specify
        curl https://passwordstate/api/generatepassword/?PasswordGeneratorID=<value>
    
        # Generate one or more Passwords based on a Password Generator option you specify
        curl https://passwordstate/api/generatepassword/?PasswordGeneratorID=<value>&Qty=<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>
    
        # 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>&Qty=<value>
        
       
        # Response
        HTTP/1.1 200           
        [
            {
                "Password": "ZHn#3+A^yc",
            }
        ]