Secret Managers
Connect HashiCorp Vault so test credentials are resolved at run time with a secretref:// reference instead of being stored in the app: where references work, how rotation is picked up, and the limits.
Overview
This guide walks you through the Secret Managers screen in Shift-Left API, from enabling the feature to testing that a secret resolves. A secret provider is a connection to an external secret store, so test credentials are fetched at run time rather than stored in the app. You reference a stored secret in your tests with a secretref:// string.
HashiCorp Vault is the supported provider. Vault works over its REST API, with KV v1 and v2 secrets engines and Vault Enterprise namespaces. The provider list on the screen also shows AWS Secrets Manager and Azure Key Vault, but those adapters are not supported in current builds (see Troubleshooting and notes below).
Explore the capability at secret managers.
Availability: Trial and Enterprise.
Before you begin
- You must be an administrator with the manage_secret_providers permission. The provider endpoints require it; without it the screen won't load.
- Have your Vault address and a Vault token ready. Vault authentication is token-only: AppRole, Kubernetes, OIDC and JWT auth methods are not supported, and the token is not renewed for you, so use a token whose lifetime suits your schedule.
- Navigate to Settings → Integrations → Secret Managers.
- The Vault Token is encrypted at rest and never displayed again. The provider card shows a configured / not set badge for it. Keep a copy before you save.
Step 1 — Enable Secret Managers
- Find the Enable Secret Managers card. When off, the helper text reads "Turn on to resolve test credentials from external secret managers."
- Click the toggle switch on the right of that card. It flips to the active (blue) state and shows the notification "Secret managers enabled." The helper text changes to "Secret managers are active. Connect and manage providers below."
- If the feature is disabled you'll see the placeholder "Secret managers are currently disabled. Use the switch above to enable them, then add a provider."
Step 2 — Add a Vault provider
- Click Add provider (top right). The form header reads Add provider.
- Fill in the fields:
| Field | What it does |
|---|---|
| Provider type | Choose HashiCorp Vault. This selection is fixed once created (it's disabled when editing). |
| Display name | A friendly name (required), e.g. Production Vault. Saving with this blank shows "Display name is required." |
| Enabled | Checkbox. When checked the provider can resolve secrets. |
| Address * | Vault base URL, e.g. https://vault.example.com:8200. |
| Token * | Vault access token, e.g. hvs.xxxxxxxx. Secret: encrypted, shown once, then a configured badge. |
| Namespace (optional) | Vault Enterprise namespace, e.g. admin. Sent as the X-Vault-Namespace header. |
| Mount (optional) | Shown on the form but not used when resolving. Include the mount in the secret path instead (for example secret/data/myapp). |
Fields marked * are required. When editing, the token field shows "Leave blank to keep the existing value."
Step 3 — Create the provider
- Click Create provider (the button reads Save changes when editing). While saving it shows Saving….
- On success you'll see "Secret provider created" and the form closes.
- The provider appears as a card showing the display name, a provider-type badge, an Enabled/Disabled badge, the generated providerId (monospace), and a configured (green) or not set (amber) badge for the token.
Step 4 — Test the connection
Each provider card has a Test connection panel:
- In Secret path, enter a path Vault can resolve, including the mount, e.g.
secret/data/myapp. This is required; an empty path shows "Enter a secret path to test." - Optionally enter a Field (optional), e.g.
password, to resolve a single key within the secret. Without a field, the whole secret is returned to the request as JSON. - Click Test (it shows Testing… while running).
- On success you'll see a green message such as "Connection succeeded. Secret resolved." The secret's value is intentionally not returned. On failure you'll see a red RESOLUTION_FAILED message with the reason.
Step 5 — Reference secrets in tests
Reference a stored secret using:
secretref://<providerId>/<path>#<field>
<providerId>: the provider id shown on the card.<path>: the secret path in Vault, including the mount (e.g.secret/data/myapp).#<field>: optional; a single key within the secret (e.g.#password).
Where a reference is resolved:
| Place | Resolved? |
|---|---|
| Request headers, query parameters and body | Yes |
| OAuth 2.0 profile fields (client secret, password and so on) | Yes |
| Sign-in-with-steps profile step requests | Yes |
| JSON-RPC / MCP and WebSocket-RPC tokens | Yes |
| Basic, API key, Bearer and similar profile fields | Not reliably; put the reference in the request header instead, or use an OAuth 2.0 or sign-in-with-steps profile |
References are resolved by the server runner (the Shift-Left Engine) at execution time, held in memory only, and never stored or shown in the browser. The local runner in the desktop app does not resolve them; a test that needs one fails with a message asking you to run it on the server runner.
Rotation: rotate the secret in Vault. Resolved values are cached for up to 30 seconds, so the next run after that picks up the new value.
Troubleshooting and notes
- AWS Secrets Manager or Azure Key Vault fails with "SDK not installed". Those two adapters need cloud SDKs that are not included in current builds, so they are not supported. Use HashiCorp Vault.
- MISSING_PATH (400): you clicked Test without a Secret path. Enter one.
- RESOLUTION_FAILED (400): Vault couldn't resolve the path or field. Recheck the Address, the token, the path (including the mount) and the Namespace.
- A reference arrives unresolved in a request: a reference that fails to resolve is left as it is and logged, and the request is still sent. Check the provider is enabled and the path resolves with Test.
- PROVIDER_EXISTS (409): a provider with that identity already exists.
- PROVIDER_NOT_FOUND (404): the provider was deleted; tests referencing it stop resolving. Deleting prompts "Delete secret provider "…"? Tests referencing it will stop resolving."
- Creating and deleting providers is written to the audit log.
Related articles
Related articles
- Administration Settings · Product documentation
- Server Connection · Product documentation
- Proxy Settings · Product documentation
- License Management: Status and Keys · Product documentation
- User Management · Product documentation
- Role Permissions · Product documentation
Next steps
- Getting started · Install + connect your spec
- Configuration fundamentals · Stabilize runs
- Initial configuration · Users, licensing, projects
- Release notes · Updates and fixes
Still stuck?
Tell us what you’re trying to accomplish and we’ll point you to the right setup—installation, auth, or CI/CD wiring.