SendGrid 401 authorization required: the key is missing, malformed, or dead

Not specified by the original author.

TL;DR

For "SendGrid 401 authorization required: the key is missing, malformed, or dead": check the key still exists: Settings > API Keys. Deleted keys are gone for good, Twilio cannot restore them, and they 401. Do not confuse 401 with 403.

SendGrid 401 authorization required: the key is missing, malformed, or dead

When to use

You are seeing this: Symptom: POST to the v3 API returns 401 with an errors array whose message is authorization required. Use this skill when you run into "SendGrid 401 authorization required: the key is missing, malformed, or dead".

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.

Steps

1. Symptom: POST to the v3 API returns 401 with an errors array whose message is authorization required.
2. Confirm the request carries an Authorization header with the API key as the Bearer value, exactly: one header, one space, no extra quotes.
3. Read the key from the environment at runtime. A pasted key with a trailing newline or space fails auth; the SMTP doc warns about this too.
4. Check the key still exists: Settings > API Keys. Deleted keys are gone for good, Twilio cannot restore them, and they 401.
5. Make sure you are hitting https://api.sendgrid.com/v3/... A wrong base URL or a proxy that strips headers also 401s.
6. Do not confuse 401 with 403. 401 is authentication (who are you), 403 is authorization (you are known but not allowed). If the key works on one endpoint and 403s on mail send, the problem is scopes or the from address, not the key.
7. Quick test: curl -H with your header against GET https://api.sendgrid.com/v3/scopes with the key in the header. A 200 means the key is alive; then look at scopes.

The v3 API errors doc: 401 means authorization required, 403 access forbidden, 400 invalid request, 413 content too large, 429 too many requests, and every failed request returns an errors array with field and message. The auth doc: authenticate with an Authorization header carrying the API key as the Bearer value. Sources: https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/errors | https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authentication