All articles

You only see the key once: how your team should store, rotate, and revoke API keys

When you generate an API key in the SimAggregator dashboard, the key string appears on screen exactly once. If you close the window without copying it, nobody can see that string again, including us: the platform stores only a fingerprint of the key, not the string itself. A lost key can't be recovered, only replaced: you generate a new one and revoke the old one. That's why it pays to set up rotation and revocation in advance, before anything leaks.

One key per environment and per service

A key acts on behalf of your account and spends its balance: whoever has the string can buy numbers at your expense. With one shared key "for everything," a leak leaves you guessing where it happened, and revoking the key breaks every integration at once.

In the dashboard you can generate several keys and give each one a name. We recommend an "environment + service" scheme: prod-bot, staging-bot, ci-tests. The name tells you right away what will stop working once you revoke the key and who to ask about strange activity. The API limit of 600 requests per minute applies per key, so a CI test run doesn't eat into your production service's requests.

CI has a catch: getNumber called from there buys real numbers from the same balance. You can't cancel such an order until at least a minute has passed. Orders canceled without a code lower your 7-day share of orders that received a code, and your account's reputation sets the limit on concurrent orders, which CI and the production bot share. For smoke checks, getBalance and getPrices are usually enough.

Where to store the key string

Right after generating a key, put it in a secrets manager or in protected CI variables that are masked in logs. Don't put it in the repository, in a .env file committed "just for now," in a team chat, or in a ticket. The developer building the integration usually doesn't need the production key string: the service pulls it from the secrets store on startup.

The API is compatible with sms-activate and accepts only GET requests, so the key travels in the query string. Make sure your HTTP client, proxies, and access logs don't record the full request URL. Logs are kept for a long time and many people can read them, so treat any key that ends up in a log as leaked.

Rotation: new key first, then revoke the old one

Rotation comes down to two actions in the dashboard: generating a new key and revoking the old one. In that order, the old key keeps working until the service switches to the new one, and no requests fail.

  1. Generate a new key with the same purpose in its name, for example prod-bot-2.
  2. Save it in your secrets manager in place of the old value.
  3. Restart the service so it picks up the new key.
  4. Check the dashboard: the new key now shows a last-used date, and the old key's date has stopped changing.
  5. Revoke the old key.

Rotate outside your regular schedule if:

  • someone who saw the key has left the team;
  • the key ended up in a log, a screenshot, a chat, or a repository;
  • you moved to a different host or CI.

Tie scheduled rotation to the same schedule you use for your other secrets.

Auditing by last-used date

Open the key list before a release or whenever you review access. A key that hasn't been used in a long time is probably left over from a closed project, so revoke it. If the staging-bot key is being used but the staging bot itself was shut down a week ago, revoke the key right away and find out where the requests are coming from. It's also easier to revoke a key with an unclear name than to guess whose it is. If someone needs it, the owner will notice through their own service and generate a new key with a clear name.

Protect the account itself

An API key is only as secure as your account: anyone who signs in to the dashboard can generate a new key for themselves and spend your balance. So turn on two-factor authentication: you set up a TOTP code from an authenticator app on the sign-in page, and that's also where you change your password. If you suspect someone else has accessed your account, end sessions on other devices, change your password, and rotate all your keys. Follow the same steps when someone who had dashboard access leaves the team.

To get started, turn on 2FA on the sign-in page. Then generate separate named keys for prod, staging, and CI in the dashboard, put them in your secrets manager, and revoke your shared key if you had one.

Your first number in a minute

Signing up takes a minute, topping up a couple more, and the code arrives in 20 seconds.

Buy a number
No subscription feeCancel with a refund in the first hour