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.

```python
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.