KeyZero with AWS Secrets Manager

AWS Secrets Manager is the native secret store for AWS workloads. KeyZero integrates with it through the standard AWS SDK credential chain, letting you resolve secrets from AWS SM alongside other backends -- without writing AWS-specific code or managing SDK calls in your application.

How the Integration Works

KeyZero uses the AWS SDK under the hood. When a secret is requested, it calls GetSecretValue with the configured secret_id. If the secret value is a JSON string and a field is specified, KeyZero extracts that field automatically. Otherwise, the raw string is returned.

Authentication follows the standard AWS credential chain: environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), shared credentials file, IAM instance profile, ECS task role, or SSO. No KeyZero-specific auth configuration is needed -- if aws secretsmanager get-secret-value works in your environment, KeyZero will too.

Prerequisites

# Install KeyZero
brew install getkeyzero/tap/keyzero

# Verify AWS access
aws secretsmanager get-secret-value --secret-id prod/api-key --region us-east-1

Ensure your IAM identity has secretsmanager:GetSecretValue permission on the secrets KeyZero will resolve.

Bundle Configuration

Define an AWS Secrets Manager backend with an optional region, then attach resolvers:

backends:
  aws:
    type: aws_secrets_manager
    region: us-east-1

resolvers:
  - name: api-key
    mode: direct
    backend: aws
    secret_id: prod/api-key
    field: api_key

  - name: db-connection
    mode: direct
    backend: aws
    secret_id: prod/database
    field: connection_string

  - name: signing-cert
    mode: direct
    backend: aws
    secret_id: prod/tls-cert
    # No field -- returns the raw secret string

The region on the backend is optional. If omitted, the SDK uses AWS_DEFAULT_REGION or the region configured in your AWS profile. The secret_id can be the secret name or a full ARN.

JSON Field Extraction

Many teams store multiple values in a single AWS SM secret as a JSON object:

{
  "api_key": "sk-live-abc123",
  "api_secret": "whsec_xyz789",
  "webhook_url": "https://hooks.example.com/ingest"
}

When field is set on the resolver, KeyZero parses the secret value as JSON and returns just that field. When field is omitted, the entire raw string is returned -- useful for single-value secrets or when your application handles JSON parsing itself.

Combining with AWS STS

For workloads that need temporary AWS credentials (not just stored secrets), KeyZero also supports an aws_sts backend. You can combine both in a single bundle:

backends:
  aws-secrets:
    type: aws_secrets_manager
    region: us-east-1

  aws-sts:
    type: aws_sts
    region: us-east-1

resolvers:
  - name: openai-key
    mode: direct
    backend: aws-secrets
    secret_id: prod/openai
    field: api_key

  - name: deploy-creds
    mode: direct
    backend: aws-sts
    role_arn: arn:aws:iam::123456789012:role/deploy
    duration_seconds: 900

The STS resolver returns a JSON object with access_key_id, secret_access_key, and session_token. This lets an AI agent or CI job get both application secrets (from Secrets Manager) and scoped AWS credentials (from STS) through a single kz run invocation.

What KeyZero Adds

Blind Mode for AI Agents

AWS Secrets Manager has no concept of opaque token swapping. When you pass a secret to an AI agent via environment variables, the agent holds the raw value. KeyZero's blind mode replaces the real credential with a kz_masked_* token before the agent process starts. A local MITM proxy intercepts outbound requests and swaps tokens for real values at the network edge.

kz run --blind -- python agent.py

The agent can authenticate with external APIs without ever seeing the actual AWS-sourced secret.

Cross-Cloud and Multi-Backend Support

Production environments often span multiple providers. A single .keyzero.toml can pull secrets from AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, and 1Password simultaneously:

backends:
  aws:
    type: aws_secrets_manager
    region: us-east-1
  gcp:
    type: gcp_secret_manager
    project: my-gcp-project
  vault:
    type: hashicorp_vault
    address: https://vault.internal

resolvers:
  - name: aws-api-key
    backend: aws
    secret_id: prod/api-key
    field: key
  - name: gcp-service-key
    backend: gcp
    path: service-account-key
  - name: vault-db-pass
    backend: vault
    path: secret/data/db
    field: password

One kz run resolves all of them. See the HashiCorp Vault integration for Vault-specific configuration details.

Local Development with the Same Config

Developers on macOS can use the same bundle file. During local development, they might override just the backend to use macOS Keychain or a local .env file, while CI and production resolve from AWS SM. The resolver definitions stay identical -- only the backend target changes between environments.

When to Use This Integration

Use KeyZero with AWS Secrets Manager when you need blind mode for AI agent workloads, cross-cloud secret unification, shell hooks for developer convenience, CEL policy enforcement beyond IAM policies, or MCP server integration for agentic frameworks. For simple server applications that only consume AWS secrets, the SDK or ECS/Lambda native integration may be sufficient on its own. To understand how the resolution pipeline works end to end, read the KeyZero architecture deep dive, or explore five patterns for secret-safe AI deployments.