Rotate an SMS API key by creating a second key, deploying it everywhere, confirming traffic has moved, and only then revoking the old one. Do it on a schedule and right away after a suspected leak. An SMS key can spend money and message real people, so a stolen one costs more than a stolen read-only token.

This playbook covers storage, scoping, rotation without downtime and what to do in the first hour after a leak. It's general practice that applies to any texting API. For the exact way Ready issues and revokes keys, check the API quickstart and the docs, since we won't guess at details here. If you need the basics first, start with what an SMS API and API key are.

Why an SMS key is worth protecting

A key in the X-API-Key header authorizes sends. Anyone holding it can send texts that cost money and carry your brand. They can also read messages and opt-out lists your account holds.

The damage comes in three forms:

  • Spend. Segments are metered. A loop or a thief sending to many numbers runs up a bill quickly.
  • Reputation. Spam sent from your registered numbers can draw carrier filtering that hurts your legitimate traffic.
  • Compliance. Texts to people who never agreed are your exposure, not the thief's.

Treat the key as a password with a bill attached.

Where keys live

Keep keys in a secrets manager or in server environment variables injected at deploy time. Never in a repository, a mobile app, a browser bundle, a support screenshot or a shared document. A key in client code is a key you've published.

PlaceVerdictWhy
Secrets managerBestAccess control, audit trail, versioning
Deploy-time environment variableGoodNot in source, easy to swap
Config file in the repoNeverLives in history forever
Mobile or browser codeNeverAnyone can extract it
Chat, email, ticketsNeverCopied, searched, retained
Application logsNeverFlows to many tools

Call the API from your server only. If a browser needs to trigger a text, it asks your backend, which holds the key and decides whether to send.

Add a pre-commit secret scanner and a repository scan in CI. Most leaks aren't attacks. They're a key pasted into a file and pushed.

One key per environment and per job

Give production, staging and development separate keys. A leaked staging key then can't send production traffic. Where your setup allows it, go further and use a separate key per service, so you can revoke one without taking down the others and so usage tells you which service misbehaved.

Testing is covered in our sandbox and test numbers guide. If you're a platform sending for your own customers, keep each customer's traffic in its own sub-account, which also limits what any one key's mistake can reach. Our multi-tenant SMS architecture post covers that structure.

Rotation without downtime

The mistake is revoking first. Do it in this order.

  1. Create a new key and store it in the secrets manager under a new version.
  2. Deploy the new key to every service that sends. Roll it out gradually if you can.
  3. Verify that traffic uses the new key. Check your logs for the key label, and watch for 401 responses.
  4. Wait an overlap window. Pick one long enough to cover your slowest job runner and any scheduled job, such as a nightly batch.
  5. Revoke the old key once the overlap window ends.
  6. Confirm afterward that nothing breaks and that no request still arrives with the old key.

The overlap window is the whole trick. For a few minutes or hours, two keys are valid, so no deploy has to be perfectly simultaneous. A rotation with no overlap needs every consumer to change in the same second, which doesn't happen.

Idempotency keys help here. If a rotation causes a few 401s and your jobs retry, the same Idempotency-Key on each retry means a send that did succeed isn't repeated. See idempotency and duplicate texts.

How often to rotate

A schedule you actually follow beats an ambitious one you skip. Quarterly or twice a year suits many teams, with an owner named for each key. Rotate immediately, outside the schedule, when:

  • someone with access to the key leaves the team or a contractor's work ends
  • the key appeared in a repository, log, ticket or screenshot
  • a laptop or CI runner that held it was lost or compromised
  • usage looks wrong and you can't explain it

Write the procedure as a runbook before you need it. A leak at 2 AM is a bad time to discover that nobody knows where the sending keys are deployed.

The first hour after a leak

When a key is exposed, speed matters more than neatness.

  1. Create a replacement key and get it into production first, so sending continues.
  2. Revoke the exposed key as soon as the replacement is live. Skip the overlap window here, because the old key is the problem.
  3. Check recent activity. Read recent messages with GET /v1/messages and look for sends you didn't make: odd destinations, odd times, odd volume.
  4. Look at billing and usage for the period the key was exposed.
  5. Check the opt-out and contact data the key could read, and decide whether an exposure notice is needed. That's a question for your counsel.
  6. Find the cause and fix it, whether that's a repository, a log line or a former employee's access.

Then write down what happened and what you changed. The second leak is usually the same cause as the first.

Watch for misuse

A key can leak without anyone telling you. The earliest evidence is usually the bill or a volume graph. A step change in segments per hour, sends to destinations you never message, or traffic at odd hours are all worth an alert. Our observability guide lists the signals and the alerts that deserve a page.

A worked example, with stated assumptions: suppose a stolen key sends 20,000 one-segment texts before anyone notices. At $0.012 per segment all-in (the $0.0075 Standard rate plus the $0.0045 carrier fee, excluding screening), that's 20,000 times $0.012. An hourly spend alert would have cut that to whatever one alert window allows. Accounts opened before November 12, 2026 keep their signup prices, shown under Billing; see pricing for the current list.

Ready's all-in prices per segment include the carrier fee but not screening: Scrub lists and Number validation, the two switches in Settings under Compliance, each add $0.003 per segment when switched on, shown as screening on your bill, and both are off by default. Unless you turn the opt-out footer off, the first text to each contact, and one again from time to time, also gets "Reply STOP to opt out" and your business name if the message does not already have them, so a text close to the segment limit can bill one more segment.

Webhooks have their own secret to protect. Verify signatures over the raw body, as covered in authentication and webhook signing, and rotate that secret with regenerate_secret on PUT /v1/webhooks. Unlike an API key, a webhook secret has no overlap: the old one stops working the moment you rotate, so deploy the new secret to your receiver as you rotate, and expect a few deliveries to fail verification in between. A delivery your receiver rejects with a 4xx is not retried automatically, so resend those from the delivery log once the new secret is live.

A rotation checklist

CheckDone when
InventoryEvery key has an owner and a list of where it's deployed
StorageAll keys sit in a secrets manager, none in the repo
SeparationProduction, staging and development use different keys
ScanningPre-commit and CI secret scans are on
RotationA schedule and a written runbook exist
OverlapThe new key is verified live before the old one is revoked
AlertsA spend alert and a 401 alert are on
Leak drillYou've practiced the first-hour steps once

Rotating keys is dull work, and that's the point. If you're ready to wire up a key, sign up, then follow the API quickstart and the messages reference.