Put the key in a secrets manager, read it at runtime from the one service that sends texts, and rotate it by adding a new version before you retire the old one. Both AWS Secrets Manager and HashiCorp Vault do this well. The choice mostly comes down to where your infrastructure already lives.
An SMS key can spend money and message real people, so it deserves better than a .env file in a repo. This guide covers the storage pattern for the X-API-Key header Ready uses, the same idea for each tool, and a rotation routine. For the wider playbook, see our SMS API key security and rotation guide.
What you're protecting
A key in the X-API-Key header authorizes sends against your account. Whoever holds it can send texts that cost money and carry your brand. Treat it like a database password with a bill attached.
That shapes the design. You want few readers, an audit trail of who read it, and a way to replace it quickly. A secrets manager gives you all three. An environment variable baked into an image gives you none.
Which tool fits
Neither tool is wrong. Pick the one your team already runs and knows how to operate.
| Question | AWS Secrets Manager | HashiCorp Vault |
|---|---|---|
| Where it runs | Managed by AWS, nothing to host | You host it, or use a managed offering |
| Access control | IAM policies on the secret | Policies on a path, tied to an auth method |
| Audit | CloudTrail records reads | Audit devices log every request |
| Versioning | Staging labels such as AWSCURRENT and AWSPREVIOUS | Versioned key/value engine |
| Best fit | Workloads already on AWS | Multi-cloud or on-prem, or short-lived dynamic secrets |
If everything you run is on AWS, Secrets Manager is the lower-effort path. If you span clouds, or you already have Vault for database credentials, add the SMS key there instead of running a second system.
Storing the key in AWS Secrets Manager
Create the secret once, from a machine that has the key and permission to write it.
import boto3
client = boto3.client("secretsmanager")
client.create_secret(Name="prod/sms/ready-api-key", SecretString=READY_API_KEY) Then give the sending service's role read access to that one secret and nothing else. Scope the IAM policy to the exact secret name, not a wildcard. The service fetches the value at startup.
key = client.get_secret_value(SecretId="prod/sms/ready-api-key")["SecretString"] Cache the value in memory for the life of the process, or for a few minutes. Don't call the secrets manager on every text. It adds latency, and it can add cost you didn't plan for.
Storing the key in HashiCorp Vault
With the key/value version 2 engine, a write creates a new version each time.
vault kv put secret/sms/ready api_key="$READY_API_KEY" Write a policy that grants read on secret/data/sms/ready only, and attach it to the identity your sender uses (a Kubernetes service account, a cloud role or AppRole). Avoid a long-lived Vault token pasted into a config file. That just moves the problem one step back.
vault kv get -field=api_key secret/sms/ready Using the key in your sender
Your code reads the secret, then sets the header on each request. A send looks like this, with a placeholder key and a fictional number.
curl https://api.tryready.com/v1/messages \
-H "X-API-Key: $READY_API_KEY" \
-H "Idempotency-Key: 3f1c9a52-7b0e-4d0a-9d55-2b7a6c1e84aa" \
-H "Content-Type: application/json" \
-d '{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}' Two habits matter here. Only the backend ever touches the key, never a browser or mobile app. And the Idempotency-Key stays the same on every retry, so a rotation hiccup that triggers retries doesn't send the same text twice. Our guide to idempotency and duplicate texts covers that in detail.
Rotating without downtime
Rotation is dull on purpose. The order is what makes it safe.
- Create the new key in Ready and store it as a new version in your secrets manager.
- Let every sending service pick it up. Restart them, or let a short cache expire.
- Watch your logs and your 401 responses until no traffic uses the old key.
- Revoke the old key.
Check the API quickstart for how keys are issued and revoked, and plan the overlap around what it says. If you suspect a leak, skip the waiting. Get the replacement live, revoke the exposed key, then read recent activity with GET /v1/messages for sends you didn't make.
AWS can run rotation on a schedule through a Lambda function, and Vault can do similar work with plugins or its own jobs. A third-party API key is a case where you often write that glue yourself, because the key is issued by the provider. A quarterly reminder with a written runbook beats an automation nobody has tested.
One key per environment, and per customer boundary
Keep production, staging and development keys in separate secrets with separate access. A leaked staging key then can't send production traffic.
If you're a platform texting on behalf of your own customers, structure matters too. Each customer lives in its own sub-account, which limits what one mistake can reach. Read our post on multi-tenant SMS architecture before you decide how many secrets you'll manage, and the sub-accounts docs for the API side.
Checklist before you ship
- The key exists in exactly one secrets manager path per environment.
- Only the sending service's identity can read it.
- No copy sits in a repo, image, CI log or ticket. A secret scanner runs in CI.
- Reads are logged, and someone looks at the log.
- A spend or volume alert fires if sending jumps unexpectedly.
- The rotation runbook exists and has been rehearsed once in staging.
A secrets manager won't stop every leak. It does make the response fast, because you know where the key lives and who can read it. Once that's in place, you're ready to sign up and send your first text.