# How to rotate a SendGrid API key

> Regenerate a Twilio SendGrid API key without a gap in email: create the new key first, update the API and SMTP settings, then delete the old key.

URL: https://crunu.com/rotate/sendgrid
Language: en
Updated: 2026-10-30

Create a second API key with the same permissions, put it everywhere the old one is used, including SMTP settings, check that mail still goes out, and delete the old key last. A SendGrid account can hold up to 100 API keys, so the two can coexist for as long as the switch takes ([Twilio docs](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys)). Twilio's own replacement steps run in the opposite order: delete the existing key, create a new one, then replace it in your code. That order leaves a window in which every send fails. Reverse it unless the old key has leaked.

Crunu doesn't regenerate or delete SendGrid keys, and it has no Twilio integration. It shows which SendGrid values a departing person or a leak exposed, keeps the new key as a new environment version, and restarts the programs that send with it.

*Figure: Timeline of rotating the API key. Step 1: a new key is issued while the old one keeps working. Step 2: every place that uses the key is updated, with no downtime because both keys work. Step 3: the old key is revoked. After revocation the old key stops working at once.*

## Pick the permission before you create the key

SendGrid offers four permission levels when you create a key:

- **Full Access** grants every API endpoint full access to the account.
- **Custom Access** lets you choose which endpoints a key can use and at what access level.
- **Billing Access** grants the billing endpoints. Billing calls need a key of their own.
- **Email Address Validation Access** covers the validation endpoints and read access to reporting.

You can't give a key more permissions than you have yourself, and you can change a key's name and permissions later. Keys created through the API default to Full Access when the request leaves out `scopes` ([API reference](https://www.twilio.com/docs/sendgrid/api-reference/api-keys/create-api-keys)), so a script that reissues keys should always send the scopes it needs, such as `mail.send`. Only a key allowed to manage other keys can create them, and the very first key of an account has to come from the SendGrid app.

The console displays a key once, at creation, and Twilio can't retrieve or restore a lost or deleted one. Keys look like `SG.xxxxxxxx.yyyyyyyy`.

## SMTP uses the same key

The reissue that breaks things is usually the one nobody remembers: SMTP. SendGrid's SMTP relay authenticates with an API key, expecting the literal word `apikey` instead of a username and the key as the password ([SMTP guide](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/getting-started-smtp)). The key needs Mail Send permission. Mail servers, a CMS or monitoring tools that relay through `smtp.sendgrid.net` all hold a copy, so list them before you delete anything.

## Reissue without a gap in email

1. In the SendGrid console, under **Settings** > **API Keys**, create a key with the same permission level as the old one, or a narrower Custom Access set if the old key was broader than it needed to be. Copy the value.
2. In Crunu, replace `SENDGRID_API_KEY` in the environment that holds it, for example `payments-api / production`, and save. The save creates a new version; the history names the variable, never the value.
3. Restart the senders. Services launched with `crunu run --restart on-change` pick up the new version without help. Update every SMTP client by hand with `apikey` as the user and the new key as the password.
4. Send a test message through each path, the API and SMTP, and check that both are accepted.
5. Delete the old key. From then on, SendGrid rejects any API call made with it.

```sh
crunu run --env payments-api/production --restart on-change -- /opt/payments/bin/mailer
```

## Know where each key lives

With room for 100 keys, a SendGrid account easily collects keys nobody can place. Name each key after the service and environment that use it, for example `payments-api production`, and give every sender its own key. A departure or a leak then means deleting one named key and replacing one value in one Crunu environment, instead of guessing which of several Full Access keys a mail server still depends on.

## When to reissue a SendGrid key

- **Someone leaves.** Reissue every key they could read, Full Access keys first. Removing them in Crunu produces a reissue checklist with those values by name, and **Where to reissue** opens SendGrid's API keys page for recognized SendGrid values.
- **A leak.** Here Twilio's order is right: delete the key at once, accept the gap, then create and deploy the replacement. A leaked Full Access key can change anything in the account.
- **On your own schedule.** SendGrid's documentation describes no expiry for API keys, so nothing forces a rotation. Put one in your calendar, and use it to delete keys that no service uses.

Revoking a key never requires changing your username and password, which makes short-lived, single-purpose keys cheap to keep. [What to rotate when a developer leaves](https://crunu.com/guides/developer-offboarding-secret-rotation) covers the rest of a departure, and the [offboarding checklist](https://crunu.com/tools/offboarding-checklist) builds the list for your own stack. The keys themselves are always created and deleted in SendGrid; Crunu records when each new value was saved and by whom.

## FAQ

### Can a SendGrid account have two API keys at the same time?

Yes. Twilio limits an account to 100 API keys, so there is room for the old and the new key during a switch. When the limit is reached, creating another key through the API returns a 403 status.

### Why does Twilio's guide delete the old key first?

Its replacement steps list deleting the existing key, creating a new one, then replacing it in code. That order leaves a window in which mail fails. Unless the old key leaked, create the new key first and delete the old one last.

### Do SMTP settings change when I reissue a SendGrid key?

Yes. SendGrid's SMTP relay authenticates with an API key: the username is the literal word apikey and the password is the key. Every mail server, CMS or tool that relays through SendGrid needs the new value.

### Does Crunu regenerate SendGrid keys?

No. Crunu doesn't call SendGrid or Twilio. It shows which SendGrid values a departing person received, stores the new key as a new environment version and restarts the services that read it through crunu run.

## Sources

- [Twilio SendGrid Docs: API keys](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys) (accessed 2026-10-30)
- [Twilio SendGrid API reference: Create API keys](https://www.twilio.com/docs/sendgrid/api-reference/api-keys/create-api-keys) (accessed 2026-10-30)
- [Twilio SendGrid Docs: How to send an email with SMTP](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/getting-started-smtp) (accessed 2026-10-30)