Create, scope and rotate API keys

Why key practice matters

An API key is a password that belongs to a program. Anyone who has it can send messages and spend your balance as if they were you. Because keys are copied into servers, build systems and chat messages, they leak far more often than people expect. Good key practice cannot prevent every leak, but it limits the damage and makes recovery fast.

Principles

• One key per application and per environment
• Store keys in a secret manager or encrypted environment variables
• Use sandbox keys in development and live keys only in production
• Give each key the least access it needs, where scopes are available
• Know who owns each key
• Rotate on a schedule and whenever someone with access leaves

Creating a key

1. Name it clearly. Use the application and environment, for example billing-service-production
2. Choose scope. Where available, allow only the actions the application needs
3. Copy it once. The key is shown only at creation. Put it straight into your secret manager
4. Record it. Add the key name, owner and creation date to your inventory (never the key itself)
5. Test it. Send one request and confirm the key works before removing any older key

Storing keys safely

Where a key lives decides how easily it leaks.

Rotating without downtime

Rotation replaces a key with a new one. Done carefully, nothing breaks.

1. Create a new key. Give it the same name with a new date
2. Deploy it. Update the secret in your manager and restart or reload the application
3. Check traffic. Confirm in Logs that requests now use the new key
4. Wait. Leave the old key active for a short overlap in case a server missed the update
5. Revoke the old key. Remove it and watch for errors

If a key leaks

1. Revoke it at once. Do this before you investigate
2. Create a replacement. Deploy it to the affected application
3. Review activity. Check Logs for messages and spend you do not recognise
4. Find the source. Check repositories, chat history and build logs
5. Fix the cause. Remove the key from where it leaked and add a scanning tool to catch future leaks
6. Tell support. If spend or messages look wrong, send us the details

Auditing your keys

• List every key, its owner and its last use each quarter
• Revoke keys unused for 90 days
• Check that no key is shared between applications
• Confirm that each key is stored in the secret manager
• Test that you can rotate one key end to end

Rotation runbook template

Write the procedure down before you need it. A short runbook turns a stressful incident into a routine task. Include the secret manager path for each key, the command or screen used to deploy a new value, the list of services that read the key and the owner to notify. Add the checks that prove success, such as a test message and a look at recent traffic by key name. Rehearse it once a year with a non-critical key. Teams that rehearse find the missing step, such as a forgotten cron job that still uses the old key, while it is harmless to find it.

Environments and naming

Use a consistent pattern such as service, environment and date. A name like crm-production-2026-10 tells you what it is for and when it was made at a glance, which makes audits and incident response much faster than a list of keys called key1 and key2.

Scopes and restricted access

Where scopes are offered, use them. A key that can only send SMS cannot read your customer lists or change your billing profile if it leaks. Start with the smallest scope that lets the application function, test it and widen only when a real requirement appears. Document the scope next to the key in your inventory so reviewers can check that each key is no more powerful than it needs to be.

Network controls

Where your plan allows it, restrict a key to a list of server addresses. An allow-list turns a leaked key into a useless string for anyone outside your network. Combine it with a firewall rule on your side so that only the servers that need to call Telnxo can reach the secret in the first place. For applications that run on changing addresses, put outbound calls through a gateway with a fixed address.

Monitoring key activity

Make key activity visible. Watch request volume, error rate and spend per key, and alert on a sudden rise. A key whose traffic triples overnight, or that starts sending to new countries, deserves immediate attention. Review the audit log each month for key creation and revocation, and compare it against your inventory. Any difference is either a gap in the inventory or an incident, and both need action.

Onboarding and offboarding

Make key hygiene part of joining and leaving a team. New engineers should receive access to the secret manager, not copies of keys. When someone leaves, rotate every key they could read, and record the rotation in your inventory. These two habits prevent the most common route by which keys stay in the hands of people who no longer need them, and they cost almost nothing once they are routine.

Review and ownership

Assign a named owner to this area and put a review on the calendar every quarter. At each review, check the metrics described above, read the last quarter's incidents and update the runbook with anything you learned. Short, regular reviews keep small drifts from turning into outages, and they make onboarding new team members far easier because the current practice is written down in one place.

Further reading

• OWASP Cheat Sheet Series: Secrets Management
• NIST SP 800-57, Recommendation for Key Management
• Telnxo guide: Balance, invoices and team access