LogoLogo
KeeperPAM and Secrets Manager
KeeperPAM and Secrets Manager
  • KeeperPAM
  • Privileged Access Manager
    • Setup Steps
    • Quick Start: Sandbox
    • Getting Started
      • Architecture
        • Architecture Diagram
        • Vault Security
        • Router Security
        • Gateway Security
        • Connection and Tunnel Security
      • KeeperPAM Licensing
      • Enforcement Policies
      • Vault Structure
      • Record Linking
      • Applications
      • Devices
      • Gateways
        • Creating a Gateway
        • Docker Installation
        • Linux Installation
        • Windows Installation
        • Auto Updater
        • Alerts and SIEM Integration
        • Advanced Configuration
          • Gateway Configuration with AWS KMS
          • Gateway Configuration with Custom Fields
      • PAM Configuration
        • AWS Environment Setup
        • Azure Environment Setup
        • Local Environment Setup
      • PAM Resources
        • PAM Machine
          • Example: Linux Machine
          • Example: Azure Windows VM
        • PAM Database
          • Example: MySQL Database
          • Example: PostgreSQL Database
          • Example: Microsoft SQL Server Database
        • PAM Directory
        • PAM Remote Browser
        • PAM User
      • Sharing and Access Control
      • Just-In-Time Access (JIT)
    • Password Rotation
      • Rotation Overview
      • Rotation Use Cases
        • Azure
          • Azure AD Users
          • Azure VM User Accounts
          • Azure Managed Database
            • Azure SQL
            • Azure MySQL - Single or Flexible Database
            • Azure MariaDB Database
            • Azure PostgreSQL - Single or Flexible Database
          • Azure App Secret Rotation
        • AWS
          • IAM User Password
          • Managed Microsoft AD User
          • EC2 Virtual Machine User
          • IAM User Access Key
          • Managed Database
            • AWS RDS for MySQL
            • AWS RDS for SQL Server
            • AWS RDS for PostgreSQL
            • AWS RDS for MariaDB
            • AWS RDS for Oracle
        • Local Network
          • Active Directory or OpenLDAP User
          • Windows User
          • Linux User
          • macOS User
          • Database
            • Native MySQL
            • Native MariaDB
            • Native PostgreSQL
            • Native MongoDB
            • Native MS SQL Server
            • Native Oracle
        • SaaS Accounts
          • Okta User
          • Snowflake User
          • Rotate Credential via REST API
        • Network Devices
          • Cisco IOS XE
          • Cisco Meraki
      • Service Management
      • Post-Rotation Scripts
        • Inputs and Outputs
        • Attaching Scripts
        • Code Examples
    • Connections
      • Getting Started
      • Session Protocols
        • SSH Connections
        • RDP Connections
        • RBI Connections
        • MySQL Connections
        • SQL Server Connections
        • PostgreSQL Connections
        • VNC Connections
        • Telnet Connections
      • Examples
        • SSH Protocol - Linux Machine
        • RDP Protocol - Azure Virtual Machine
        • MySQL Protocol - MySQL Database
        • PostgreSQL Protocol - PostgreSQL Database
    • Tunnels
      • Setting up Tunnels
    • Remote Browser Isolation
      • Setting up RBI
        • URL Patterns & Resource URL Patterns
        • Browser Autofill
    • Session Recording & Playback
    • SSH Agent
      • Integration with Git
    • Discovery
      • Discovery Basics
      • Discovery using Commander
      • Discovery using the Vault
    • On-Prem Connection Manager
    • References
      • Port Mapping
      • Setting up SSH
      • Setting up WinRM
      • Setting up SQL Server
      • Database Import and Export
      • Installing sqlcmd on Linux
      • Installing Docker on Linux
      • Creating KSM App for Rotation
      • Active Directory Least Privilege
      • Event Reporting
      • Importing PAM Records
      • Managing Rotation via CLI
      • Commander SDK
      • Cron Spec
      • Preview Access
  • Endpoint Privilege Manager
    • Overview
    • Setup
    • Deployment
    • Policies
    • Managing Requests
  • FAQs
  • Secrets Manager
    • Secrets Manager Overview
    • Quick Start Guide
    • About KSM
      • Architecture
      • Terminology
      • Security & Encryption Model
      • One Time Access Token
      • Secrets Manager Configuration
      • Keeper Notation
      • Event Reporting
      • Field/Record Types
    • Secrets Manager CLI
      • Profile Command
      • Init Command
      • Secret Command
      • Folder Command
      • Sync Command
      • Exec Command
      • Config Command
      • Version Command
      • Misc Commands
      • Docker Container
      • Custom Record Types
    • Password Rotation
    • Developer SDKs
      • Python SDK
      • Java/Kotlin SDK
        • Record Field Classes
      • JavaScript SDK
      • .NET SDK
      • Go SDK
        • Record Field Classes
      • PowerShell
      • Vault SDKs
    • Integrations
      • Ansible
        • Ansible Plugin
        • Ansible Tower
      • AWS CLI Credential Process
      • AWS Secrets Manager Sync
      • AWS KMS Encryption
      • Azure DevOps Extension
      • Azure Key Vault Sync
      • Azure Key Vault Encryption
      • Bitbucket Plugin
      • Docker Image
      • Docker Runtime
      • Docker Writer Image
      • Entrust HSM Encryption
      • Git - Sign Commits with SSH
      • GitHub Actions
      • GitLab
      • Google Cloud Secret Manager Sync
      • Google Cloud Key Management Encryption
      • Hashicorp Vault
      • Heroku
      • Jenkins Plugin
      • Keeper Connection Manager
      • Kubernetes External Secrets Operator
      • Kubernetes (alternative)
      • Linux Keyring
      • Octopus Deploy
      • Oracle Key Vault Encryption
      • PowerShell Plugin
      • ServiceNow
      • TeamCity
      • Teller
      • Terraform Plugin
        • Terraform Registry
      • Windows Credential Manager
      • XSOAR
    • Troubleshooting
  • Commander CLI
    • Commander Overview
    • Installation and Setup
      • CLI Installation on Windows
      • CLI Installation on macOS
      • CLI Installation on Linux
      • Python Developer Setup
      • .NET Developer Setup
      • PowerShell Module
      • Logging in
      • Configuration and Usage
        • AWS Secrets Manager
        • AWS Key Management Service
      • Automating with Windows Task
      • Automating with AWS Lambda
      • Uninstallation
    • Command Reference
      • Import and Export Data
        • Import/Export Commands
        • CyberArk Import
        • LastPass Data Import
        • Delinea / Thycotic Secret Server Import
        • Keepass Import
        • ManageEngine Import
        • Myki Import
        • Proton Pass Import
        • CSV Import
        • JSON Import
      • Reporting Commands
        • Report Types
      • Enterprise Management Commands
        • Creating and Inviting Users
        • Compliance Commands
        • Breachwatch Commands
        • SCIM Push Configuration
      • Record Commands
        • Record Type Commands
        • Creating Record Types
      • Sharing Commands
      • KeeperPAM Commands
      • Connection Commands
        • SSH
        • SSH Agent
        • RDP
        • Connect Command
        • SFTP Sync
      • Secrets Manager Commands
      • MSP Management Commands
      • Miscellaneous Commands
      • Password Rotation
        • Password Rotation Commands
        • AWS Plugin
        • Azure Plugin
        • Microsoft SQL Server Plugin
        • MySQL Plugin
        • Oracle Plugin
        • PostgreSQL Plugin
        • PSPasswd Plugin
        • SSH Plugin
        • Unix Passwd Plugin
        • Windows Plugin
        • Active Directory Plugin
        • Automatic Execution
    • Service Mode REST API
    • Troubleshooting
Powered by GitBook

Company

  • Keeper Home
  • About Us
  • Careers
  • Security

Support

  • Help Center
  • Contact Sales
  • System Status
  • Terms of Use

Solutions

  • Enterprise Password Management
  • Business Password Management
  • Privileged Access Management
  • Public Sector

Pricing

  • Business and Enterprise
  • Personal and Family
  • Student
  • Military and Medical

© 2025 Keeper Security, Inc.

On this page
  • About
  • Notation
  • Fetching Records by Name
  • Escaping notation characters
  • Using Name to Simplify Environment Switching

Was this helpful?

Export as PDF
  1. Secrets Manager
  2. About KSM

Keeper Notation

Query format used for getting fields of a secret

PreviousSecrets Manager ConfigurationNextEvent Reporting

Last updated 6 months ago

Was this helpful?

About

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

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.

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:

[
  {"number": "123-456-7890", "type": "work"},
  {"number": "555-555-5555", "type": "home"}
]

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.

SDKs
integrations
click here