How to rotate a SendGrid API key

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). 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.

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), 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). 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

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 covers the rest of a departure, and the 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.