Keeper Notation

Query format used for getting fields of a secret

About

Keeper notation is used by Keeper Secrets Manager SDKs and integrations to query fields in Keeper records. To view the different types of records and the field names available, click here.

Notation

keeper://<TITLE|UID>/<type|title|notes>

keeper://<TITLE|UID>/file/<filename|title|fileUID>

keeper://<TITLE|UID>/<field|custom_field>/<label|type>[[predicate1][predicate2]]

The notation is broken up into four parts.

  • Title or UID of the secret record

  • The selector of the record data. There are three types:

    • short selectors without any additional parameters - type, title, and notes

    • file selector accepts a single parameter - file name, title or UID

    • full selector specifies the filed type - field or custom_field, and requires additional parameters

  • The parameters used for full selectors must specify the field type or label that selects a unique field in the record, and predicates are optional

  • The predicates are optional indexes further into field value. The first predicate is the numeric index into the value array, and the second index is a property index (in case of a complex value)- ex. .../custom_field/name[1][middle]

The first predicate is always required in order to use the second predicate. Please use one of the following examples: phone[0][number] - get only the first number for the first phone (even if the array contains only one phone) phone[][number] - get a CSV list of all numbers from all phones in the value array

Predicates

The predicate allows finer access to the value. Some values might be a single value or an array of values, and each of those values might be a string or a dictionary of values.

Arrays If no predicate is defined only one value will be returned. If the returned value contains an array of values, only the first one will be returned. If a predicate with a number is defined, e.g. phone[0] the value at that index is returned. Indexes start at 0.

If a predicate with no value is defined, e.g. phone[], the array value will be returned.

Sub Fields Some field values are made up of other sub fields. For example:

"fields": [
    { "type": "name", "value": [ 
        {"first:": "John", "last": "Doe"},
        {"first:": "Jane", "last": "Doe"} ]
    },
    { "type": "phone", "value": [
        {"number": "555-5555555", "ext": "55"}, 
        {"number": "777-7777777", "ext": "77"} ]
    }
]

To access sub fields, include the name of the field as an alphanumeric predicate. For example name[0][first] will find "John" in the example above, and name[1][first] will find "Jane".

Mixed

Some values are a combination of the arrays and Sub Fields. For example:

[
    {"number": "555-5555555", "ext": "55"}, 
    {"number": "777-7777777", "ext": "77"}, 
    {"number": "888-8888888", "ext": "", "type": "Home"}, 
    {"number": "999-9999999", "type": "Work"}
]

To get a specific value you can use the first numeric predicate to get the whole value - ex. phone[1] will return the full value for the second phone {"number": "777-7777777", "ext": "77"} To get a specific sub field, a double predicate is needed. For example, the predicate phone[1][number] will return only the phone number of the second value.

Fetching Records by Name

Keeper Secrets Manager SDKs support Keeper Notation fetching of records by record name.

Escaping notation characters

If any part of the record contains "/" "\" "[" or "]" you will need to escape that character with a backslash. These special characters are used by notation as internal section and index delimiters and need to be escaped if present in the record title, field label or file name.

Examples:

Title: "Twitter Login [Marketing]" keeper://Twitter Login \[Marketing\]/field/password URL custom field with Label: "/. links" keeper://My Slashdot Links/custom_field/\/.links[] (all links) keeper://My Slashdot Links/custom_field/\/.links[1] (2nd link only) File name: "creds[2].crt" keeper://My \/. Credentials/file/creds\[2\].crt

Using Name to Simplify Environment Switching

With the Keeper Notation record title fetching capability, it is possible to create your notation queries once, and use them across different build environments by utilizing different Secrets Manager Applications.

Example:

In this example, two shared folders have been created. One for developer environments and one for production. Inside each folder there are identically named records. These records have the same name, but different credentials stored in them.

Each shared folder will be associated with a different Secrets Manager application.

In the associated Secrets Manager integration, use notation to fetch the credentials. For example: keeper://MySQL Creds/field/password In integrations used for development builds, use the Secrets Manager application associated to the Dev folder (in this case "Development Environment"). Then to build for production, simply change the associated Secrets Manager application to "Production Environment" no change in code or scripts needed.

PreviousSecrets Manager ConfigurationNextEvent Reporting

Last updated

Was this helpful?