Skip to main content
A secret store lets Runlayer resolve a connector’s upstream credentials from your secret manager at connection time, instead of storing them in Runlayer. Runlayer’s database holds only a reference like secretref://prod-aws/runlayer/jira#api_key; the secret value is fetched when a connection is made, held in memory only, and never persisted or logged.

​
What This Changes

  • At-rest exposure stays low. A compromise of Runlayer’s database yields references, not credentials.
  • Rotation without Runlayer. Rotate the secret in AWS; new connections pick up the new value within the cache window (about 2 minutes). Existing connections keep the value resolved when they connected.
  • Runtime access still exists. The Runlayer data plane still reads the secret at resolve time. Secret stores remove at-rest exposure, not runtime exposure.
Secret stores currently support AWS Secrets Manager. Additional backends, including HashiCorp Vault, are on the roadmap.

​
Set up an AWS Secrets Manager store

Runlayer generates an External ID for each store when you create it — you don’t invent one. The setup order is therefore: create the role, register the store, then paste the generated External ID into the role’s trust policy.
1

Create the IAM role

In the AWS account holding your secrets, create a role Runlayer can assume. Give it read access to the secrets you intend to reference:
Start with a trust policy that allows Runlayer’s account to assume it. For self-hosted deployments, use your backend’s IAM role ARN as the principal instead. You will tighten the policy with the External ID after registering the store:
A separate, scoped IAM role is required for every store, including self-hosted deployments. Runlayer always assumes that role with the store’s External ID. It never reads referenced secrets directly with the backend’s IAM role. Multiple stores can share a role if its trust policy allows each store’s External ID.
2

Register the store

Open Settings → Secret Stores and click Add secret store in the header. Enter a name, the AWS region for the secrets, and the role ARN from the previous step, then click Create.The dialog moves to Finish connecting and shows the generated External ID, such as rl:3f2a.... Copy this value. If you close the dialog, Finish setup on the store’s row reopens it, and Edit always shows the External ID.
3

Add the External ID to the trust policy

Add the sts:ExternalId condition to the role’s trust policy using the value from the previous step. This is the confused-deputy protection: Runlayer sends this store’s External ID on every assume-role, and the condition ensures only Runlayer acting for your store can assume the role.
4

Test the connection

After updating the trust policy, return to Runlayer and click Test connection in the Finish connecting dialog (or in Edit). The store’s row then shows Connected or Connection failed with the reason; Test again re-runs the check. When an admin opens the page, a store last checked more than a day ago is checked again automatically.The test verifies that Runlayer can assume the role using the store’s External ID; it does not verify secretsmanager:GetSecretValue for a particular secret. Use the connector’s connection test to verify access to each referenced secret.

​
Reference Secrets from Connectors

Anywhere a remote connector’s transport configuration takes a header value, you can use a reference instead:
  • <store-name> — the store name from Settings → Secret Stores.
  • <secret-name-or-arn> — the Secrets Manager secret name or full ARN.
  • #<json-field> — optional; when the secret value is a JSON object, selects one key. Omit it to use the whole secret string.
  • The full value must be the secretref://... reference. Embedded references inside a larger string are not resolved.
References resolve where Runlayer itself opens the connection: header values of remote (HTTP/SSE) connectors. They do not resolve in env values that Runlayer passes to a process it doesn’t proxy at connect time:
  • Hosted stdio connectors run as a Runlayer Deploy container, and Runlayer Deploy env reaches the container as-is. Runlayer rejects a secretref:// value there instead of passing the literal string. To keep a credential in your AWS account, have the server read it at runtime with AWS cross-account roles.
  • Local stdio connectors run on the user’s machine with the configured env, so a reference would reach the process unresolved.
Examples:
For bearer-token headers, store the complete header value in AWS, such as:
Then reference the authorization field:
The server’s connection test resolves references too, so a misconfigured store or missing permission fails with an actionable message before anything ships. For a safe rotation, keep the old and new credentials valid at the same time when the upstream supports it. Update the AWS secret, wait for the cache window, then reconnect or drain existing sessions before revoking the old credential. Long-lived sessions do not re-resolve secret references in place, so revoking the old credential immediately can interrupt them.

​
Behavior Details

​
Permissions

  • Viewing stores: organization settings admins, connector admins, and Deploy users can view the page when secret stores are enabled.
  • Managing stores: only organization settings admins can create, update, delete, and test stores.
  • Referencing stores: connector admins can reference stores in connector config. The store list is visible to them for that purpose.

​
Saving a browser login from Go

When browser logins are enabled, an agent that needs a new website login can show Add login in the Go conversation. The dialog identifies the HTTPS site and the Secret Store that will receive the username and password. Credentials are submitted directly to the backend’s vault endpoint; the conversation and agent receive only the login name, site, and completion status. If the site asks for a code from an authenticator app after the password, add its Authenticator key too: the setup key shown with the site’s two-factor QR code, or its otpauth://totp/ link. It is saved in the same secret, under the totp field. At sign-in, Runlayer computes the current codes from it and the sign-in browser enters the one the site asks for. Neither the agent nor the sign-in browser ever receives the key. Codes sent by SMS or email, push approvals and passkeys aren’t supported. Saving requires permission to edit the agent and connector or organization settings administration. The AWS role must also allow creating secrets. Existing stores configured with only GetSecretValue can continue supplying saved logins, but cannot accept new ones from this dialog. Add the following statement to the store role’s policy, replacing the region, account, and organization ID. Keep the existing read permission for this prefix:
Each request creates one secret in the selected store under runlayer/browser-logins/<organization-id>/<agent-id>/<request-id>. Retries reuse that request’s secret; the form cannot choose an arbitrary secret path or overwrite an existing login. The agent’s saved login holds only references to the secret’s username and password fields, plus its totp field when an authenticator key was added. Skip saves nothing. If saving fails, the request remains pending and the agent does not continue. A successful save allows the conversation to continue; it does not prove that the website accepted the login. SSO and unsupported second factors may still block it. Secrets belong to the organization’s AWS account. Removing a saved login or deleting a request does not delete the AWS secret. Administrators manage rotation and deletion in Secrets Manager and revoke the store role when offboarding the organization. If a request is cancelled while an AWS write is already in flight, a secret may remain in AWS without an attached login. Concurrent submissions to different stores can also leave an unused secret; only the first completed save attaches a login to the agent.

​
Offboarding and cleanup

Browser logins belong to the agent, not the person who saved them. Use an account approved for the agent’s work: removing the saving user’s access does not revoke that website account or remove the agent’s saved login. These checks apply to new sign-ins. They do not revoke website sessions already issued to a browser. Revoke those sessions at the website as part of offboarding. An organization administrator should perform this cleanup before deleting records needed for the inventory:
  1. Find the departing user’s agent_browser_login_changed audit events and record the affected agent IDs and login names. Review agent_browser_login_used events for subsequent use.
  2. In each agent’s browser login settings, record the Secret Store and secret path from its saved references. Disable the agent if access must stop immediately, then remove or replace the affected logins. Rotate personal credentials and revoke existing sessions at the website.
  3. In every Secret Store that could have received a save, inventory secret names under runlayer/browser-logins/<organization-id>/<agent-id>/. The final path segment is the Go request ID. Compare these names with the saved references; this also identifies unattached secrets left by interrupted or concurrent saves. Secret values are not needed for this inventory.
  4. Schedule deletion of unused secrets in AWS Secrets Manager according to your retention policy. For organization offboarding, inventory the entire runlayer/browser-logins/<organization-id>/ prefix in every configured store, revoke the role’s access, and delete the secrets.
Secret creation does not configure automatic rotation or expiry. The AWS administrator owns that policy. Organization, agent, and request IDs are in the secret name; the saving user’s identity is in the Runlayer audit trail, not an AWS ownership tag. Keep the inventory with your offboarding record before removing agents, requests, or audit history.