# How the Agent Toolkit for AWS Handles Secrets Management: Architecture and Best Practices

> Discover how the Agent Toolkit for AWS centralizes secrets management in AWS Secrets Manager. Learn best practices for secure credential handling and automated rotation. Enhance your security posture today.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: architecture
- Published: 2026-06-28

---

**The Agent Toolkit for AWS centralizes secrets management in AWS Secrets Manager, enforcing least-privilege IAM policies, runtime SDK retrieval, and automated rotation while prohibiting hard-coded credentials through guardrail rules.**

The `aws/agent-toolkit-for-aws` repository provides a security-first framework for AI coding agents that eliminates hard-coded credentials by integrating deeply with AWS native services. Its approach to secrets management spans specialized skills, IAM guardrails, and runtime retrieval patterns to ensure sensitive data never appears in source code or static configuration files.

## AWS Secrets Manager as the Central Store

The toolkit designates **AWS Secrets Manager** as the default location for all credentials, API keys, and sensitive configuration values. In [`skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/SKILL.md), the `creating-secrets-using-best-practices` skill defines a complete workflow for provisioning secrets with dedicated KMS keys and automatic rotation enabled.

### Best-Practice Defaults for Secret Creation

According to [`skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md), the toolkit enforces encryption at rest using customer-managed KMS keys, configures rotation schedules via Lambda functions, and applies lifecycle tags for cost tracking.

```bash
aws secretsmanager create-secret \
    --name "my-app/db-credentials" \
    --secret-string '{"username":"admin","password":"<generated>"}' \
    --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:SecretsRotation \
    --rotate-immediately

```

## Runtime Secret Retrieval Patterns

Skills retrieve secret values at execution time using the AWS SDK, ensuring credentials never persist in code repositories. The documentation in [`skills/specialized-skills/serverless-skills/aws-lambda-microvms/references/snapshots-and-uniqueness.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/serverless-skills/aws-lambda-microvms/references/snapshots-and-uniqueness.md) shows that secrets are fetched from Secrets Manager on each VM resume, preventing snapshot contamination.

```python
import boto3

def get_secret(secret_arn: str) -> str:
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId=secret_arn)
    return response['SecretString']

# Usage in Lambda-managed instances

DB_PASSWORD = get_secret("arn:aws:secretsmanager:us-east-1:123456789012:secret:rds-db-credentials/cluster-ABCDEF")

```

## IAM Policies and Least-Privilege Enforcement

Execution roles attach granular IAM policies that scope permissions to specific secret ARNs. The reference documentation in [`creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md) specifies exact actions: `secretsmanager:GetSecretValue`, `DescribeSecret`, and `PutSecretValue`.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-app/db-credentials*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/<kms-key-id>"
    }
  ]
}

```

## Parameter Store Fallback for Amplify Workflows

For Amplify-generated applications, the toolkit acknowledges that `secret()` references map to **AWS Systems Manager Parameter Store** SecureString parameters. The documentation in [`skills/specialized-skills/web-and-mobile-development/aws-amplify/references/deployment.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/web-and-mobile-development/aws-amplify/references/deployment.md) advises reviewing `/amplify/` parameter path permissions while noting that sandbox secrets set via `npx ampx sandbox secret set` do not propagate to production environments.

## Enforcement and Developer Tooling

The toolkit combines automated policy enforcement with helper utilities to maintain secrets management standards across all skills.

### Guardrail Rules Against Hard-Coded Secrets

The [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md) file contains guardrail policies that flag any attempt to embed raw credentials in skill code, forcing agents to adopt the secret-retrieval pattern instead.

### Helper Scripts and CLI Workflows

Reusable shell functions in [`skills/specialized-skills/database-skills/rds-db2/scripts/functions.sh`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/database-skills/rds-db2/scripts/functions.sh) wrap `aws secretsmanager get-secret-value` for common workflows like DB2 credential injection, abstracting the SDK calls behind simple command-line interfaces.

## Summary

- **AWS Secrets Manager** serves as the central repository for all sensitive values, with mandatory KMS encryption and rotation support.
- **Runtime retrieval** via the AWS SDK (`boto3`, `@aws-sdk/client-secrets-manager`) ensures secrets never appear in source code or snapshots.
- **Least-privilege IAM policies** restrict access to specific secret ARNs and require KMS decryption permissions.
- **Amplify integration** maps secrets to Parameter Store SecureString parameters while maintaining environment separation.
- **Guardrail rules** automatically reject hard-coded credentials, enforcing compliance across the `aws/agent-toolkit-for-aws` repository.

## Frequently Asked Questions

### Does the Agent Toolkit for AWS support secret rotation?

Yes. The `creating-secrets-using-best-practices` skill configures automatic rotation using Lambda functions when provisioning new secrets. The rotation configuration includes immediate rotation on creation and scheduled updates to minimize credential lifespan, as documented in [`skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/security-and-identity-skills/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md).

### Can skills use environment variables instead of Secrets Manager?

No. The toolkit explicitly discourages environment variables for sensitive values. The [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md) guardrails flag hard-coded secrets, and specialized skills like RDS DB2 and Lambda Managed Instances document strict Secrets Manager requirements in their migration patterns.

### How does the toolkit handle secrets in local development environments?

For local Amplify development, the toolkit provides `npx ampx sandbox secret set` to inject secrets into the sandbox environment. However, these values remain isolated and do not propagate to production deployments, preventing accidental credential leakage.

### What permissions does a skill need to access secrets?

According to [`creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/creating-secrets-using-best-practices/references/create-secrets-using-best-practices.md), execution roles require `secretsmanager:GetSecretValue` and `secretsmanager:DescribeSecret` actions scoped to the specific secret ARN, plus `kms:Decrypt` permissions for the associated customer-managed key.