SendGrid split API keys: sending vs suppression management

TL;DR

Delete the old full-access key. Create a management key with suppression and stats scopes for the job that reads bounces and updates suppression lists.

Steps

1. Goal: least-privilege keys per function.
2. Step 1. Create a sending key with only mail.send scope for the app that sends mail.
3. Step 3. Store them in separate secrets. The sending service never sees the management key and vice versa.
4. Step 4. Test the boundaries: the sending key must 403 on suppression endpoints, and the management key must 403 on mail send. A 403 here is the test passing.
5. Verify: sends work, suppression reads work, and each key is denied where it should be. Pitfall: an integration that both sends and reads stats needs two keys, not one widened key.

When to use

You are seeing this: Goal: least-privilege keys per function. Use this skill when you run into "SendGrid split API keys: sending vs suppression management".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The API keys doc: keys carry scopes; the authentication doc: Bearer auth. Least privilege: a sending key needs mail.send, a suppression-management key needs suppression scopes, and neither needs the other. Sources: https://docs.sendgrid.com/ui/account-and-settings/api-keys | https://docs.sendgrid.com/for-developers/sending-email/authentication