engineering-handbook/confluence/05-secrets-and-configuration.md

Secrets and Configuration

Sensitive and non-sensitive configuration are kept strictly apart.

AWS Secrets Manager: sensitive values

Use Secrets Manager for every sensitive value:

• API tokens and keys
• Signing secrets used to verify requests
• Webhook URLs that act as authentication
• Connection strings containing passwords
• Anything that would cause harm if leaked

If you are unsure whether something is sensitive, treat it as sensitive.

Name secrets <stack-name>/<value-name>, for example my-stack/stripe-key.

SSM Parameter Store: non-sensitive values

Use Parameter Store only for non-sensitive configuration:

• Feature flags
• Public endpoint URLs
• Schedule expressions
• Non-sensitive identifiers, such as channel IDs
• Resource names that deploy pipelines read, such as bucket names and function names

Reading secrets in a Lambda

1. Store the value in Secrets Manager.
2. Grant the function's role secretsmanager:GetSecretValue on only the secrets it needs.
3. Read the secret on cold start and cache it in a module-level variable.

import json

import boto3

_client = boto3.client("secretsmanager")
_cached = None


def get_config():
    global _cached
    if _cached is None:
        resp = _client.get_secret_value(SecretId="my-stack/config")
        _cached = json.loads(resp["SecretString"])
    return _cached


def handler(event, context):
    config = get_config()
    # use config values

Never

• Put sensitive values in Lambda environment variables. They show in plain text in the AWS console.
• Commit .env files or any file containing real credentials.
• Share credentials in Jira, Confluence, Slack, email, or any other plain-text tool.
• Hardcode account IDs, ARNs, or resource names that belong in configuration.

If a secret is committed or exposed by mistake, tell your technical point of contact immediately so it can be rotated. Deleting the commit is not enough.