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

# Secrets Manager

> Keep the secrets your tasks read in your organization's own AWS account: create and rotate them in the portal or with the AWS CLI through AI Reserve, inject them with secrets[].valueFrom, roll back by version.

Your organization's AWS container account comes with **AWS Secrets Manager**.
A secret you create there is injected into a task at start through the task
definition's `secrets[].valueFrom`, read by the AWS CLI or any SDK with an
[ECS credential](/containers/ecs), and listed, versioned, deleted and restored
from the portal under **Secrets › Secrets Manager**. The portal never shows a
value: it is written once, and read only by the task or your shell.

Isolation is AWS's own account boundary — the same one that keeps your
clusters yours. A secret's ARN carries your account id, and nothing in any
other organization's account is reachable from it.

## One setting

The same endpoint override you set for ECS, for the Secrets Manager service:

| Setting | Value |
| - | - |
| Environment variable | `AWS_ENDPOINT_URL_SECRETS_MANAGER=https://api.aireserve.com` |
| Shared-config key (`[services aireserve]`) | `secrets_manager =` / `endpoint_url = https://api.aireserve.com` |
| Credential | the ECS credential pair from **Containers & Orchestration › Elastic Container Service › Create credential** |

```bash theme={"dark"}
export AWS_ACCESS_KEY_ID="AIRA…"
export AWS_SECRET_ACCESS_KEY="…"
export AWS_DEFAULT_REGION="us-east-1"
export AWS_ENDPOINT_URL_SECRETS_MANAGER="https://api.aireserve.com"

aws secretsmanager list-secrets --include-planned-deletion
```

An empty `SecretList` is a success. Or, in `~/.aws/config`, next to the ECS lines:

```ini theme={"dark"}
[services aireserve]
ecs =
  endpoint_url = https://api.aireserve.com
cloudwatch_logs =
  endpoint_url = https://api.aireserve.com
secrets_manager =
  endpoint_url = https://api.aireserve.com
```

## Create and read

```bash theme={"dark"}
# The value comes from stdin so it never lands in shell history.
printf '%s' "$DATABASE_URL" | aws secretsmanager create-secret \
  --name prod/api/database-url \
  --description "Postgres URL the api service reads at start" \
  --secret-string file:///dev/stdin \
  --tags Key=aireserve:managed,Value=cli

aws secretsmanager get-secret-value --secret-id prod/api/database-url \
  --query SecretString --output text
```

The portal's **Create secret** button is `create-secret` (tagged
`aireserve:managed=portal`); its detail panel carries this exact
`get-secret-value` line with the endpoint export above it, ready to paste.
Names are up to 512 characters of letters, numbers and `/ _ + = . @ -`; a
path such as `prod/api/database-url` reads well in a task definition.

## Inject into a task

Reference the secret by ARN in a container's `secrets` array; ECS resolves
it when the task starts and sets the environment variable:

```json theme={"dark"}
{
  "name": "DATABASE_URL",
  "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/api/database-url-AbCdEf"
}
```

For a JSON-valued secret, one key: append `:key::` to the ARN
(`…:secret:prod/api/credentials-AbCdEf:password::`). The task execution
role your account ships with (`AireserveEcsTaskExecution`) may read secrets,
so nothing else is needed. The portal's secret detail panel copies this entry
with the ARN filled in; the **Variables** dialog of a deployed service takes
the same `NAME=<ARN>` lines.

## Versions and rollback

Every `put-secret-value` (the portal's **Update value**) stores a new
version and moves the `AWSCURRENT` label onto it; the version that was
current becomes `AWSPREVIOUS`. Tasks that start from then on, and every
`get-secret-value`, read `AWSCURRENT`; tasks already running keep what they
started with until they are replaced (a **Redeploy** does that).

```bash theme={"dark"}
printf '%s' "$NEW_DATABASE_URL" | aws secretsmanager put-secret-value \
  --secret-id prod/api/database-url --secret-string file:///dev/stdin

aws secretsmanager list-secret-version-ids --secret-id prod/api/database-url --include-deprecated
```

To roll back, move `AWSCURRENT` to an older version — the portal's **Make
current** button on the Versions list:

```bash theme={"dark"}
aws secretsmanager update-secret-version-stage --secret-id prod/api/database-url \
  --version-stage AWSCURRENT \
  --move-to-version-id <older version id> \
  --remove-from-version-id <current version id>
```

No value changes; only the label moves.

## Delete and restore

Deletion is scheduled, never immediate: a 7–30 day recovery window
(the portal offers 7, 14 or 30; 30 is the default) during which the secret
is recoverable with `restore-secret`. Tasks that reference a scheduled
secret fail to start right away, and no version can be read — that is the
signal to restore.

```bash theme={"dark"}
aws secretsmanager delete-secret --secret-id prod/api/database-url --recovery-window-in-days 30
aws secretsmanager restore-secret --secret-id prod/api/database-url
```

The portal's **Delete** asks for the recovery window and shows the date;
**Restore** appears on a secret while it is scheduled. There is no
force-delete from the portal.

## From an agent

The [MCP containers domain](/connect/mcp-tools#containers-containers-query-containers-action)
has `list_secrets`, `get_secret` (metadata and versions only),
`promote_secret_version`, `delete_secret` and
`restore_secret`. A value an agent stores is one the user handed it; no value
ever comes back over that connection — the agent points the user at the
`get-secret-value` line instead.

> [!NOTE]
>
> Secrets Manager's own charges (per secret per month, per 10,000 API calls) are AWS resources in your account and are
> metered to your wallet like the rest of it. Rotation with a Lambda function is not available in the container account
> today; rotate with `put-secret-value`.


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