> For the complete documentation index, see [llms.txt](https://newdocs.keeper.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://newdocs.keeper.io/en/release-notes/enterprise/keeper-secrets-manager/2026/ruby-sdk-17.2.0.md).

# Ruby SDK 17.2.0

### Updates

* **KSM-883:** Added throttle retry with exponential backoff. HTTP 403 `{"error":"throttled"}` responses are retried up to 5 times (11s, 22s, 44s, 88s, 176s ±25% jitter), honoring `retry_after` when present. Raises `ThrottledError` once retries are exhausted. No caller changes required.
* **KSM-906:** Added IL5 custom server public key support. `SecretsManager` accepts the 4-part `IL5:clientKey:serverPublicKeyId:serverPublicKey` OTT, registers the supplied EC P-256 key for transmission-key wrapping, and persists it across restarts. `IL5:`-prefixed tokens route to `il5.keepersecurity.us`. Adds `server_public_key` / `server_public_key_id` constructor options (precedence: programmatic > token > config).
* **KSM-1013:** Added `KeeperRecordLink` typed accessor class and `KeeperRecord#get_links`. Each link exposes permission booleans with `allowedSettings` fallback (top-level wins), AES-256-GCM decryption via `get_decrypted_data` / `get_link_data`, and `meta` / `ai_settings` / `jit_settings` settings accessors — all non-raising. Adds `request_links:` keyword to `get_secrets`. Purely additive; the raw `record.links` list is unchanged.
* **KSM-687:** Added DTO fields and PAM transaction support: `complete_transaction(record_uid, rollback: false)`, `UpdateOptions`, `update_secret_with_options`, `download_thumbnail`, `is_editable` / `inner_folder_uid` / `links` on `KeeperRecord`, `thumbnail_url` / `last_modified` on `KeeperFile`, and `expires_on` on `SecretsManagerResponse`. Reaches full parity with other SDKs.
* **KSM-692:** Added HTTP proxy support. Pass `proxy_url:` at initialization, or set `HTTPS_PROXY` / `https_proxy` in the environment; authenticated proxies are supported. Applies to all HTTP operations.
* **KSM-686:** Added `CachingPostFunction` and `Cache` for encrypted, file-based API response caching (disaster recovery pattern). Cache location is configurable via `KSM_CACHE_DIR`.
* **KSM-694:** Added `upload_file_from_path(owner_record_uid, file_path, file_title: nil)` for direct disk-to-record file upload, and `try_get_notation(notation_uri)` for error-safe notation access (returns empty array instead of raising).
* **KSM-743:** Added transmission key #18 for Gov Cloud Dev environment support.
* **KSM-1099:** Added `create_secret_with_options(create_options, record_data, folders: nil)` — accepts pre-fetched folders to skip the extra `get_folders` network call. `create_secret` is an unchanged backward-compatible wrapper.
* **KSM-1100:** Added `get_notation_results` / `try_get_notation_results` — list-returning notation lookup that always returns `Array[String]` with all field values (no first-element shortcut) and JSON-serializes complex types. `try_get_notation_results` never raises; returns `[]` on error.
* **KSM-1101:** Added `inflate_field_value(uids, replace_fields)` / `get_inflate_ref_types(field_type)` for field-reference resolution. `addressRef` resolves to address fields; `cardRef` resolves to paymentCard, text, pinCode, and address fields with recursive inflate.
* **KSM-1102:** Added `save(record, transaction_type: nil, links_to_remove: nil)` / `save_with_options(record, update_options)` — non-finalizing update aliases that use the stored record key without re-fetching and do not call `complete_transaction`. Use `save(record, transaction_type: 'rotation')` to stage a PAM rotation and finalize separately.
* **KSM-1070:** Removed the silent AES-CBC fallback in `decrypt_aes_gcm`. An authentication-tag failure now raises `DecryptionError` immediately; tampered or wrong-key ciphertext previously could produce output without any error.
* **KSM-1088:** `delete_secret` and `delete_folder` now log an error for each item whose `responseCode` is not `"ok"`, surfacing partial-failure details that were previously silent.
* **KSM-987:** `url_safe_str_to_bytes` and `base64_to_bytes` now raise `Error` naming the affected field when passed `nil`, instead of propagating a cryptic standard-library error. All Base64 decoding in `core.rb` routes through `Utils`.
* **KSM-824:** `KeeperRecord#to_h` now always includes `"custom": []` in V3 API payloads when no custom fields are set, matching Commander and Vault behavior.
* **KSM-685:** Fixed `CreateOptions.subfolder_uid` not being sent in the create payload.
* **KSM-734:** Fixed notation lookup raising an ambiguity error when the same record UID appears as both an original record and a shortcut.
* **KSM-696:** Config files created by the SDK now use `0600` permissions on Unix (owner read/write only).
* **KSM-1090:** Declared `base64` and `logger` as explicit runtime gemspec dependencies; both were removed from Ruby's default standard library in Ruby 4.0.

### **Resources**

* [RubyGems package](https://rubygems.org/gems/keeper_secrets_manager/versions/17.2.0)
* See [Ruby SDK Documentation](/en/keeperpam/secrets-manager/developer-sdk-library/ruby-sdk.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://newdocs.keeper.io/en/release-notes/enterprise/keeper-secrets-manager/2026/ruby-sdk-17.2.0.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.