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

# AWS Secrets Manager

> Read workspace credentials from AWS Secrets Manager.

A pointer with `from: aws-sm` reads a secret from
[AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) when the
workspace starts. The value stays in the memory of the process running the
workspace; see [how credentials work](https://docs.mirage.strukto.ai/home/service-credentials.md).

## Install

> [tab] Python
>
> Install the extra where Mirage runs:
>
> ```bash theme={null}
> # the mirage CLI
> uv tool install 'mirage-ai[aws-sm]'
> # a Python project
> uv add 'mirage-ai[aws-sm]'
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> npm install @aws-sdk/client-secrets-manager
> ```

## Give Mirage access

Mirage uses the AWS SDK's
[standard credentials](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html):
environment variables, a profile, SSO or an instance role. The region comes
from the profile, `AWS_DEFAULT_REGION` in Python or `AWS_REGION` in TypeScript.

That identity needs `secretsmanager:GetSecretValue` on the secrets the
workspace reads, and `kms:Decrypt` if a secret uses a customer managed key:

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

## Store a secret

```bash theme={null}
aws secretsmanager create-secret \
  --name mirage/slack \
  --secret-string '{"SLACK_BOT_TOKEN":"xoxb-your-token"}'
```

A secret holding a JSON object of strings gives each field name as a `key`.
A secret holding any other text is read with `key: value`. Mirage reads
`SecretString` only, not binary secrets.

## Point at it

```yaml workspace.yaml theme={null}
mounts:
  /slack:
    vfs: slack
    config:
      token:
        from: aws-sm
        ref: mirage/slack
        key: SLACK_BOT_TOKEN
```

`ref` is the secret's name or ARN.

## Use other credentials

To read with credentials other than the process's own, such as a second
account, declare a source with its own settings and use its name in `from`:

```yaml workspace.yaml theme={null}
secrets:
  prod:
    source: aws-sm
    config:
      region: us-east-1
      aws_access_key_id:
        from: env
        key: PROD_AWS_ACCESS_KEY_ID
      aws_secret_access_key:
        from: env
        key: PROD_AWS_SECRET_ACCESS_KEY

mounts:
  /slack:
    vfs: slack
    config:
      token:
        from: prod
        ref: mirage/slack
        key: SLACK_BOT_TOKEN
```

| Setting | Meaning |
| - | - |
| `region` | The region to read from. |
| `aws_access_key_id`, `aws_secret_access_key` | An access key, set together. |
| `aws_session_token` | The session token for temporary keys. |
| `aws_profile` | A profile from your AWS config files. |

Keys in a source's config can read only from `env` or a dotenv file.

## Cloudflare Workers

A Worker has no AWS credential files or default chain, so the source's config
must give `region`, `aws_access_key_id` and `aws_secret_access_key`.
`aws_profile` isn't available. See
[Read secrets from AWS and 1Password](https://docs.mirage.strukto.ai/typescript/cloudflare-quickstart.md#read-secrets-from-aws-and-1password).


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