> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret Stores

> Keep connector credentials in your own AWS Secrets Manager. Runlayer stores references, not secret values

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:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-east-1:<your-account>:secret:runlayer/*"
    }
  ]
}
```

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:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::<runlayer-account-id>:root" },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

> [!NOTE]
>
> 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)
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.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::<runlayer-account-id>:root" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "rl:3f2a..." }
      }
    }
  ]
}
```

**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:

```text theme={null}
secretref://<store-name>/<secret-name-or-arn>#<json-field>
```

* `<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.

> [!NOTE]
>
> 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](https://docs.runlayer.com/platform-deploy.md#aws-cross-account-roles-hosted-only).
> * **Local stdio connectors** run on the user's machine with the configured
>   env, so a reference would reach the process unresolved.

Examples:

```text theme={null}
# Header value where the AWS field stores the full "Bearer ..." string:
Authorization: secretref://prod-aws/runlayer/jira#authorization

# Secret whose name starts with /:
X-API-Key: secretref://prod-aws//team/key

# Env value for a stdio server:
API_KEY=secretref://prod-aws/my-service-api-key
```

For bearer-token headers, store the complete header value in AWS, such as:

```json theme={null}
{
  "authorization": "Bearer sk-..."
}
```

Then reference the `authorization` field:

```text theme={null}
Authorization: secretref://prod-aws/runlayer/jira#authorization
```

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

| Behavior | Value |
| - | - |
| Rotation lag | Resolved values are cached in memory for about 2 minutes; new connections pick up the new value within that window, while existing connections keep their originally resolved value until reconnect |
| Feature flag disabled | Store management and new secret resolutions stop after the flag change propagates (up to about 5 minutes). Cached values are not used for new resolutions; existing connections keep their already-resolved values until reconnect |
| AWS outage | Fresh cached values remain usable until their authorization window expires (at most about 2 minutes); failed refreshes then fail closed. Expired values are never served |
| Access revoked or secret deleted in AWS | Fails with an actionable error on the next AWS fetch; fresh cached values may be used for up to about 2 minutes |
| Deleting a store | Allowed even while referenced; subsequent connection preparation fails with "store not found". Preparation already in progress may finish, and existing connections keep their already-resolved values |
| Reusing a store name | Creating another store with a deleted store's name rebinds existing name-based references on subsequent connection preparation. The replacement never reuses the deleted store's cache |
| Secret values | Must be non-empty. A `#field` must select a JSON string; numbers, booleans, nulls, arrays, and objects are rejected instead of converted. Values are not trimmed or otherwise normalized |
| Newlines | Resolved HTTP header values containing CR or LF are rejected. Stdio environment values may be multiline and are preserved exactly |
| Binary secrets | Not supported; `SecretString` only |
| Audit | Store create, update, and delete operations are audit-logged; resolution failures are logged and metered. Secret values never appear in logs or audit entries |

## 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:

```json theme={null}
{
  "Effect": "Allow",
  "Action": "secretsmanager:CreateSecret",
  "Resource": "arn:aws:secretsmanager:us-east-1:<your-account>:secret:runlayer/browser-logins/<organization-id>/*"
}
```

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.

| Event | Result |
| - | - |
| SCIM deactivation or directory-user deletion | The user becomes inactive. Their run tokens cannot request new browser sign-ins. Agent logins and AWS secrets remain; another authorized, active run principal can still use the agent's logins. |
| Runlayer user row deleted | A user-started run whose creator is missing cannot request new browser sign-ins. Agent-owned login references and AWS secrets have no supplier-user ownership and are not automatically removed. |
| Agent disabled or deleted | New browser sign-ins are blocked, including from existing runs. AWS secrets remain. |
| Organization offboarded | Revoke the Secret Store role's access in AWS, disable the agents, and remove the organization's secrets using the steps below. Runlayer does not delete customer-owned AWS secrets. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.