Fetch secrets with boto3, parse JSON secrets, cache values between requests, handle rotation and access errors, inject secrets into ECS tasks, and test locally with moto.

AWS Secrets Manager is where a Python service on AWS usually keeps its database passwords and API keys, and boto3 reads them with a single call. The trouble sits around that call, in JSON secrets, a fetch on every request, rotation under a running process and AccessDeniedException after deploy.
This guide covers reading, caching, rotation, IAM and local tests with boto3 on Python 3.9 or later.
Install boto3 and create one client per process. It picks up credentials from the default provider chain, which on ECS means the task role and on a laptop means your profile or SSO session. Secrets created in the console as key/value pairs are stored as a JSON string, so the helper below, saved as secrets_helper.py, parses them and caches the result for five minutes:
import json
import time
from typing import Any
import boto3
from botocore.exceptions import ClientError
client = boto3.client("secretsmanager", region_name="eu-west-1")
_cache: dict[str, tuple[float, dict[str, Any]]] = {}
TTL_SECONDS = 300
def get_secret(secret_id: str) -> dict[str, Any]:
now = time.monotonic()
hit = _cache.get(secret_id)
if hit and now - hit[0] < TTL_SECONDS:
return hit[1]
try:
resp = client.get_secret_value(SecretId=secret_id)
except ClientError as err:
code = err.response["Error"]["Code"]
if code == "ResourceNotFoundException":
raise KeyError(secret_id) from err
raise # AccessDeniedException, DecryptionFailure, ...
value = json.loads(resp["SecretString"])
_cache[secret_id] = (now, value)
return value
A call such as get_secret("prod/billing/stripe")["api_key"] then costs one API request every five minutes per process. SecretId accepts the name or the full ARN. Names are convenient, but the ARN carries a six-character random suffix, so IAM policies written against the name need a wildcard such as prod/billing/stripe-?????? to match it.
The GetSecretValue API is billed per call and adds a network round trip, and a busy service that reads a secret per request pays for both. AWS publishes aws-secretsmanager-caching for this, which wraps the client and refreshes each value in the background of later reads:
import json
import boto3
from aws_secretsmanager_caching import SecretCache, SecretCacheConfig
client = boto3.client("secretsmanager")
# Values are refreshed after secret_refresh_interval seconds (default 3600).
cache = SecretCache(config=SecretCacheConfig(secret_refresh_interval=300), client=client)
def database_url() -> str:
creds = json.loads(cache.get_secret_string("prod/orders/db"))
return f"postgresql://{creds['username']}:{creds['password']}@{creds['host']}:5432/orders"
The default refresh interval is one hour, which is fine for API keys that rarely change and too long for a database password on a 30-day rotation schedule unless your connection code retries on an authentication failure.
Rotation creates a new version labelled AWSPENDING, sets the new password on the database, and then moves AWSCURRENT to it. A process holding the old value keeps working until the old password stops being valid, so the safe pattern is to catch the authentication error, clear the cached value and fetch again once. The single-user rotation strategy invalidates the old password immediately, while the alternating-users strategy keeps the previous user valid until the next rotation, which gives cached values more room.
The role the code runs as needs secretsmanager:GetSecretValue on the secret's ARN. Secrets encrypted with the AWS managed key aws/secretsmanager need nothing more, while a customer managed KMS key also needs kms:Decrypt on that key, and a missing kms:Decrypt shows up as AccessDeniedException with a message about the key rather than the secret.
On ECS you can skip the SDK call and let the agent inject the value, by listing it under secrets in the container definition with valueFrom set to the secret ARN, or to arn:...:secret:name:api_key:: for one JSON key. ECS resolves the value with the task execution role when the task starts, so a rotated value reaches the container only after a new deployment.
moto intercepts boto3 calls in-process, so a pytest test can create the secret and call the helper without network access or AWS credentials:
import json
import boto3
from moto import mock_aws
import secrets_helper
@mock_aws
def test_get_secret(monkeypatch):
monkeypatch.setenv("AWS_DEFAULT_REGION", "eu-west-1")
client = boto3.client("secretsmanager", region_name="eu-west-1")
client.create_secret(Name="prod/billing/stripe", SecretString=json.dumps({"api_key": "sk_test_1"}))
secrets_helper.client = client
assert secrets_helper.get_secret("prod/billing/stripe")["api_key"] == "sk_test_1"
By default moto does not evaluate IAM policies, so a passing test says nothing about whether the deployed role can read the secret.
Encore works alongside your Python framework, here FastAPI, as an SDK that declares infrastructure in code, and a secret is one of those declarations. Encore for Python is in private beta, and you can request an invite. The code names the secret and reads .value, while the value itself is set per environment with the CLI and never lives in the repository.

# billing/main.py
import encore
import httpx
from encore.secrets import Secret
from fastapi import FastAPI
# Declared here, valued per environment with `encore secret set`.
stripe_key = Secret[str]("StripeKey")
app = FastAPI()
@app.post("/refunds/{payment_intent}")
async def refund(payment_intent: str) -> dict:
async with httpx.AsyncClient(timeout=10) as client:
resp = await client.post(
"https://api.stripe.com/v1/refunds",
headers={"Authorization": f"Bearer {stripe_key.value}"},
data={"payment_intent": payment_intent},
)
resp.raise_for_status()
return {"refund_id": resp.json()["id"]}
if __name__ == "__main__":
encore.run(app)
Values are set once per environment type, and encore run picks up the local one:
The service is registered with an encore.service.json file next to the code, and the SDK needs Python 3.9 or later.
When the app deploys to your own AWS account, Encore stores the values in AWS Secrets Manager and injects them into the service's containers at runtime, as the AWS infrastructure docs describe, and Encore provisions an IAM role for the service. There is no get_secret_value call, cache or JSON parsing in the code, and the value is read once per process, so a new value reaches the service when it restarts.
Secret values are not stored in the repository or in git, which matters once coding agents work in it: an agent can add Secret[str]("ShippoKey") next to the handler that needs it and run the service locally, and a production value is not in the repo or in git, so it is not in the agent's context.
Request a private-beta invite to try this setup:
Create a client with boto3.client("secretsmanager") and call get_secret_value(SecretId="name-or-arn"). The value is in SecretString, which holds a JSON object when the secret was created as key/value pairs, so parse it with json.loads. Binary secrets come back in SecretBinary instead.
No. Each call adds latency and is billed per 10,000 API calls, so cache the value in the process. The aws-secretsmanager-caching library does this with a default refresh interval of one hour, and a small dictionary with a timestamp works for simple services.
secretsmanager:GetSecretValue on the secret's ARN. If the secret is encrypted with a customer managed KMS key, the role also needs kms:Decrypt on that key. On ECS, attach this to the task role, or to the execution role when ECS injects the secret as an environment variable.
Use moto's mock_aws decorator or context manager, which intercepts boto3 calls in-process so a test can create a secret and read it back. Encore uses a different model, where encore run supplies local secret values set with encore secret set --type local, so no AWS calls happen during development. Encore for Python is in private beta (sign up at /py).
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.