Query format used for getting fields of a secret
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.
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
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:
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:
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.
Use these examples as a reference for writing Keeper Notation queries. Note that each of these examples use a sample record UID.
Replace the UID in examples with the record UID for your own record when utilizing Keeper Notation
Query the type, title or notes from a record
keeper://EG6KdJaaLG7esRZbMnfbFA/type
keeper://EG6KdJaaLG7esRZbMnfbFA/title
keeper://EG6KdJaaLG7esRZbMnfbFA/notes
Query the password from a login record
keeper://EG6KdJaaLG7esRZbMnfbFA/field/password
returns: RX$u!h!pBzDGhR4Jr6#b (Randomly generated password from record)
Query the first name from a contact record
keeper://3FXqmP5nFKwju0H8pl0DmQ/field/name[first]
returns: 'Craig'
Query a file from a record
keeper://bf3dg-99-JuhoaeswgtFxg/file/credentials.txt
returns: b"jNxmJkhbZ[...]6jQtE" (contents of credentials.txt)
Query a custom Pin Code field with the label 'code'
keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/code
returns: 5876 (pin code)
Query a Two-Factor Code field from a login record
keeper://aj3dg-9ecJuhoa-sdyehg/field/oneTimeCode
returns: 5876891
Query the 2nd of several custom field phone numbers
keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/phone[1]
returns: {"number": "555-555-5555", "type": "home"}
Get just the number of this phone field
keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/phone[1][number]
returns: "555-555-5555"
Get all phone numbers on the record as an array
keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/phone[]
returns:
Keeper Secrets Manager SDKs support Keeper Notation fetching of records by record name.
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
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.
