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

# AWS Secrets Manager

> Connect your AWS account to fetch centrally managed secrets into the Requestly vault and reference them in API requests with the {{vault:key}} syntax.

Connect your AWS account to pull centrally managed secrets into the [Vault](/api-client/vault). AWS secrets share the same `{{vault:key}}` namespace as local secrets, so your requests don't need to know where a secret comes from.

<Note>
  AWS Secrets Manager integration requires **Requestly authentication** and an **eligible plan**. Local vault remains fully functional without signing in.
</Note>

***

## Setting up an AWS provider

<Steps>
  <Step title="Open the Vault page">
    Click **Vault** in the app footer.
  </Step>

  <Step title="Connect a secret manager">
    Click **Connect a secret manager** below the Local Secrets section.
  </Step>

  <Step title="Enter AWS credentials">
    Fill in the configuration form:

    | Field                 | Required | Description                                                    |
    | --------------------- | -------- | -------------------------------------------------------------- |
    | **Display Name**      | Yes      | A label for this configuration (e.g., "Production", "Staging") |
    | **Access Key ID**     | Yes      | Your AWS IAM access key                                        |
    | **Secret Access Key** | Yes      | Your AWS IAM secret key                                        |
    | **Region**            | Yes      | AWS region (e.g., `us-east-1`)                                 |
    | **Session Token**     | No       | Required only for STS temporary credentials                    |
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to validate your credentials against AWS. You can still save even if the test fails and fix credentials later.
  </Step>

  <Step title="Save">
    Click **Save**. The AWS Secrets Manager section appears on the Vault page.
  </Step>
</Steps>

***

## Required AWS IAM permissions

Your IAM user or role needs the following permissions:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:*"
    }
  ]
}
```

<Tip>
  Scope the `Resource` to specific secret ARNs for least-privilege access instead of using `*`.
</Tip>

***

## Adding and fetching secrets

<Steps>
  <Step title="Add a secret mapping">
    In the AWS Secrets Manager section, click **Add Secret**. Enter:

    * **Alias**: the key you'll use in `{{vault:alias}}`
    * **Secret Name or ARN**: the AWS secret identifier
    * **Mode**: `Plaintext` or `JSON`
  </Step>

  <Step title="Fetch the secret">
    Click **Fetch** on the secret row. Requestly calls the AWS `GetSecretValue` API and stores the result encrypted locally.
  </Step>

  <Step title="Use it in a request">
    Reference the secret using `{{vault:alias}}` in any request field. It resolves on send just like a local secret.
  </Step>
</Steps>

***

## JSON secrets

When an AWS secret contains a JSON object, Requestly auto-expands it into dot-separated keys:

```
AWS Secret "dbCredentials":
{
  "username": "admin",
  "password": "s3cret",
  "host": "db.example.com"
}
```

This creates three vault entries:

* `{{vault:dbCredentials.username}}` resolves to `admin`
* `{{vault:dbCredentials.password}}` resolves to `s3cret`
* `{{vault:dbCredentials.host}}` resolves to `db.example.com`

Nested JSON objects expand recursively with dot notation.

***

## Refreshing secrets after rotation

Fetched values are cached locally and persist indefinitely. They survive app restarts and don't auto-expire. When your team rotates a secret in AWS:

1. Open the Vault page
2. Click **Refresh** on the secret (or **Refresh All** to update all AWS secrets)
3. The new value replaces the cached one immediately

The **Last Fetched** timestamp on each secret helps you judge staleness.

<Warning>
  There is no automatic refresh. If a secret is rotated in AWS, you must manually refresh to pick up the new value.
</Warning>

***

## Multiple AWS configurations

You can store multiple AWS configurations (e.g., Production, Staging, EU region) and switch between them:

1. Click the **config selector** in the AWS section header
2. Select a different configuration. The secrets table swaps to that config's secrets.
3. `{{vault:key}}` references resolve from the **active** configuration only

Each configuration maintains its own independent set of secrets and cached values. Switching configs preserves all caches, so no re-fetching is needed.

To add a new configuration, select **+ Add new configuration** from the config selector dropdown.

***

## Credential errors

When AWS credentials expire or become invalid:

* The affected secret row shows an error message
* The provider config section shows an error indicator
* Previously cached values **remain available**. Requests continue working with the last fetched value.

To fix: edit your credentials in the same provider config form (no separate reauthentication flow), save, and retry the fetch.

***

## Move to Local

You can convert any AWS secret to a local vault secret:

1. Select **Move to Local** on an AWS secret
2. The secret moves to the Local Secrets section with the last fetched value preserved
3. It becomes fully editable and is no longer linked to AWS

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I use multiple AWS accounts at the same time?">
    You can store multiple AWS configurations, but only one is active at a time. The active config's secrets are the ones that resolve via `{{vault:key}}`. Switch between configs using the config selector in the AWS section header.
  </Accordion>

  <Accordion title="Do vault secrets auto-refresh when rotated in AWS?">
    No. Fetched values are cached locally and persist until you manually refresh. Click **Refresh** on a secret (or **Refresh All**) to pull the latest value from AWS.
  </Accordion>

  <Accordion title="Can scripts modify AWS secrets?">
    No. `rq.vault.set()` and `rq.vault.unset()` only work on local secrets. AWS secrets are read-only from scripts. Use `rq.vault.get()` to read them.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

* [Vault Overview](/api-client/vault)
* [`rq.vault` Scripting API](/api-client/rq-api-reference/rq-vault)