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.

Notation

Format
Examples
keeper://<UID>/<field|custom_field|file>/<label|type|filename>[<predicate>[predicate]]
The notation is broken up into three parts.
  • UID of the secret record
  • The field to get from the secret record. There are three types: field, custom_field, and file.
  • The type of field, the label or field of the custom field, or the name of the file attachment.

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 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 am 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 with the record UID for your own record when utilizing Keeper Notation
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 credentials 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 the just number of this phone number
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"}
]
Export as PDF
Copy link
On this page
About
Notation