Comment on page
Keeper Notation
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.
Format
Examples
keeper://<TITLE|UID>/<type|title|notes>keeper://<TITLE|UID>/file/<filename|title|fileUID>keeper://<TITLE|UID>/<field|custom_field>/<label|type>[[predicate][predicate]]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 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 fields are made up of other sub fields.
e.g.
name: {"first:": "John", "last": "Doe"}To access sub fields, include the name of the field as an alphanumeric predicate.
For example
name[last] will find "Doe" in the example above, and name[first] will find "John".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 field, a double predicate is needed. For example, the predicate
phone[1][number] will return 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.txtreturns:
b"jNxmJkhbZ[...]6jQtE" (contents of credentials.txt)
Query a custom Pin Code field with the label 'code'
keeper://aj3dg-9ecJuhoa-sdyehg/custom_field/codereturns:
5876 (pin code)
Query a Two-Factor Code field from a login record
keeper://aj3dg-9ecJuhoa-sdyehg/field/oneTimeCodereturns:
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:
[
{"number": "123-456-7890", "type": "work"},
{"number": "555-555-5555", "type": "home"}
]
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\]/fields/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\].crtWith 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/fields/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.
Last modified 3mo ago