keeper-secrets-manager-api-patterns

# Keeper Secrets Manager Tools & API Patterns ## Overview Keeper Secrets Manager (KSM) is Keeper's machine-access product: an *application* is granted access to specific shared folders in a Keeper vault, and clients authenticate as that application rather than as a person. This plugin documents the KSM tool surface reached through the WYRE Conduit gateway, which fronts Keeper's [ksm-mcp](https://github.com/Keeper-Security/keeper-mcp-golang-docker) server. Two boundaries govern everything here, and they sit in different places: - **What the connection can see** is set in Keeper, by the KSM application's folder grants. Conduit cannot widen it. See [application-setup](../application-setup/SKILL.md). - **What the connection can do** is set at the bridge: v1 is **read-only**, enforced by an allowlist, not by a setting. ## The v1 tool surface — nine tools | Tool | Tier | Returns | |------|------|---------| | `list_secrets` | read | Record metadata for the application's scope; optional folder filter | | `list_folders` | read | Folders shared to the application | | `health_check` | read | Server and KSM connectivity status | | `get_server_version` | read | Upstream server version | | `search_secrets` | **admin** | Record metadata matching a query — but the *match* runs over notes and field values, so a hit reveals that the query string appears in a secret | | `get_secret` | **admin** | A full record; sensitive fields masked unless `unmask: true` | | `get_field` | **admin** | One value, addressed by KSM notation | | `get_totp_code` | **admin** | A live TOTP code for a record carrying a TOTP field | | `generate_password` | **admin** | A generated password string | `search_secrets` is the one whose tier does not follow from its return value. It returns metadata — `uid`, `title`, `type`, `folder` — and nothing else. But it matches case-insensitively against the record's notes and the values of its `login`, `url`, `hostname` and `address` fields, so a caller who never receives a secret can still ask "does any record in scope contain this substring?" and get a reliable yes/no. That is a confirmation oracle over credential material, so it is classified **admin** even though its response carries no secret. Read the tier from what a tool can *reveal*, not from what it returns. The tier is Conduit's access classification, not a Keeper concept. Four tools sit at read: `list_secrets`, `list_folders`, `health_check`, and `get_server_version`. Five tools require admin, including `search_secrets`. Finding records by searching secret contents needs that admin grant. ## What is not exposed, and why Ten upstream tools are blocked at the bridge. They are absent from `tools/list`, and a direct call returns an error rather than executing. Do not plan around them or offer them. The **reason** column matters when someone asks for one to be turned on. Eight are withheld by policy — a decision that could in principle be revisited. Two are blocked because they do not work at the pinned upstream version; no policy change would make them functional. | Blocked tool | Why | Category | |--------------|-----|----------| | `create_secret`, `update_secret`, `delete_secret` | Vault writes | Policy | | `create_folder`, `delete_folder` | Vault structure writes | Policy | | `upload_file` | Vault writes | Policy | | `get_all_secrets_unmasked` | One call dumps every secret in the application's scope, unmasked, into model context | Policy — permanent | | `ksm_execute_confirmed_action` | Upstream's confirmation-bypass executor | Policy — permanent | | `get_record_type_schema` | Returns `record templates not loaded` on every call at the pinned version | **Broken upstream** | | `download_file` | Cannot return file contents, in any configuration | **Broken upstream** | The two permanent entries stay blocked even if a later version enables writes. When a user asks for a bulk export of their vault, the answer is that the capability is deliberately absent — then offer the read-side equivalent: `list_secrets` for the inventory, and `get_field` per value actually needed. ### The two broken-upstream entries, in detail Both were exposed in an earlier draft of this integration and removed after the upstream source was read. Knowing *why* saves a technician from diagnosing a healthy connection, and saves anyone from filing a request to re-enable them. **`get_record_type_schema`** would have returned a record type's field schema. The embedded templates are loaded by a function the shipped server never calls — `LoadRecordTemplates` has no non-test caller and the package has no `init` — so `GetSchema` always takes its templates-are-nil branch and every call fails with `record templates not loaded. Call LoadRecordTemplates first`. A message naming an internal function reads like a server fault; it is not one, and it is not fixable from the client. Nothing is lost: **`get_secret` with `unmask` unset is the better answer anyway.** Its response keys *are* the field names KSM notation addresses, read from the actual record rather than from a type template, with sensitive values masked. Skills route field-name discovery there not as a workaround but because it is the correct tool for the question. **`download_file`** is not available through this connection. Do not describe a workaround that fetches attachment bytes. **Attachments are therefore not retrievable through this connection at all.** `get_secret` still lists them — `name`, `title`, `size`, `type` — so the correct response to "send me the VPN profile from that record" is to confirm the attachment exists, name it and its size, say which record holds it, and send the user to the Keeper vault to download it. ### Stripped arguments One allowed tool has its write-capable arguments **stripped from both the advertised schema and the inbound call**, so the affordance is never visible: | Tool | Stripped | Would otherwise | |------|----------|-----------------| | `generate_password` | `save_to_secret`, `folder_uid` | Create a record | `generate_password` therefore always returns the password to the caller. It cannot be used as Keeper's "generate without showing the AI" flow — that flow requires the stripped arguments. Treat its output as secret material like any other. ## Connection & authentication The credential is configured **in the Conduit connection UI**, not on the technician's machine and not in local environment variables. One field: | Field | Label in Conduit | Value | |-------|------------------|-------| | `configBase64` | KSM Base64 Configuration | The KSM application's device configuration, base64-encoded (starts `ewog…`) | Get it from Keeper Vault → **Secrets Manager** → the application → **Devices** tab → **Add Device**, choosing the base64 configuration output. The blob decodes to JSON containing `clientId`, `privateKey`, `appKey` and `hostname`; the bridge validates that shape and returns **HTTP 401** if it does not decode to it. It never falls back to any other credential, which is what keeps one tenant's request from reaching another tenant's vault. The configuration is a device credential, not a user credential. It carries the application's scope and nothing else — no vault-wide access, no admin console access, no ability to re-share. ## Scope is the application, not the vault Every list, search and get is bounded by the folders shared to the KSM application. A record the application cannot see does not appear in `list_secrets`, is not found by `search_secrets`, and returns not-found by UID. That is correct behaviour, not a failure: - Do not report "record not found" as an outage or a broken credential. Confirm scope first with `list_folders`. - Do not conclude a vault is empty because `list_secrets` came back short. It reflects one application's grants. ## Error handling | Symptom | Meaning | Action | |---------|---------|--------| | HTTP 401 from the gateway | `configBase64` missing, not base64, or missing a required key | Re-submit the connection in Conduit with a fresh device config | | `no active session` | The upstream server has no usable KSM configuration | Connection-level problem; re-submit the credential | | Tool absent from `tools/list` | Either blocked by the read-only allowlist (policy) or broken in the pinned upstream — the two are not the same and only one could ever be revisited | Not recoverable client-side — check the blocked table above for which reason applies | | `record not found` | Out of the application's scope, or the UID is wrong | `list_folders`, then `search_secrets` by title | | `field '<name>' not found` | Field name is not on the record | Inspect the record with a masked `get_secret`; its keys are the field names | | `failed to parse notation: …` | Malformed KSM notation | See [notation-queries](../notation-queries/SKILL.md) | | `invalid UID: UID must be between 16 and 32 characters` | A title was passed where a UID is required | Resolve the title to a UID first | | `search query contains suspicious patterns` | The query contains a word the input validator rejects | Search a different token — see [finding-secrets](../finding-secrets/SKILL.md) | | Tool named in a request is not in the list above | Blocked — see the table for whether it is policy or broken upstream | Do not retry; say which it is | | `no TOTP field found in secret` | The record carries no TOTP seed | Record content, not permissions | Tool failures arrive as JSON-RPC error code `-32002`; a rate-limit rejection arrives as `-32029` with `Rate limit exceeded`. ## A note on confirmation prompts Upstream ksm-mcp asks a human to confirm unmasking and every write, over the terminal. Do not describe unmasking to a user as "confirmed by Keeper"; the control that is actually enforcing anything is the allowlist, plus the application's own scope. ## Related Skills - [finding-secrets](../finding-secrets/SKILL.md) — discovery and UID resolution - [retrieving-credentials](../retrieving-credentials/SKILL.md) — masking semantics and handling discipline - [notation-queries](../notation-queries/SKILL.md) — `get_field` notation grammar - [application-setup](../application-setup/SKILL.md) — scoping the KSM application before connecting