API keys and security

An API key can do everything its scopes allow, paid from your balance. Treat it like a password.

Key format

Keys look like sgk_ followed by 40 letters and digits. SmsGrab stores only a fingerprint of each key, so a key is shown once, when you create or rotate it, and never again. In your account you only see its beginning and its last four characters.

Limit what each key can do

When you create or edit a key, you can restrict it:

Use one key per application or server, with the smallest scopes it needs. An account can have up to 10 active keys.

Confirming sensitive changes

Creating a key, rotating it, adding a webhook, rolling a webhook secret and loosening a key (more scopes, a wider IP list, a higher cap or a later expiry) ask for your password again, plus your two-step code if it is on. The confirmation stays valid for 5 minutes. Revoking a key and tightening its limits never ask.

Rotate without downtime

Rotate gives a key a new secret while keeping its settings, usage and webhooks. You choose a grace period of up to 72 hours during which the old secret still works, so you can update your servers without an interruption.

Revoke

Revoke stops a key at once and for good. Its webhooks are switched off as well.

If a key has leaked

1. Revoke it, or rotate it with a grace period of 0 hours.
2. Check the key's request log (last 7 days) and your Wallet for activity you do not recognise.
3. Create a new key with an IP allowlist and a daily spend cap.

What we log

Keys never appear in any log. For each request we keep the time, the route, the status, the duration and a request id for 7 days, and you can see them per key. Creating, rotating and revoking keys also appear in your account activity, and every new key triggers a notification.

Never from a browser

The API does not accept calls from web pages (there is no CORS). Call it only from your own servers.