Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Email delivery

SendGrid rejects your API key from Node.js

Error401 Unauthorized

Short answer

SendGrid answers 401 when the Authorization header is missing or the key is unknown, and 403 when it knows the key but refuses the action. Check the exact header format first, then whether the key still exists, then what permissions the key has. A lost key cannot be recovered: create a new one.

  • Applies to SendGrid Web API v3, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Call the API with plain curl, outside your app, using the key from the same environment variable. This shows whether the key or your code is the problem.

    curl -i -X POST https://api.sendgrid.com/v3/mail/send \
      -H "Authorization: Bearer $SENDGRID_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"personalizations":[{"to":[{"email":"you@example.com"}]}],"from":{"email":"verified-sender@example.com"},"subject":"Test","content":[{"type":"text/plain","value":"Test"}]}'
  2. 2Match what you see, then jump to its fix

    1. 1401 with "authorization required" even though the key was just createdThe Authorization header is not in the Bearer formFix
    2. 2401 on every call; the key is missing from the API Keys pageThe key was deleted, or you copied it wrongly when it was createdFix
    3. 3403 with "access forbidden" on /v3/mail/sendThe key exists but has no permission for sending mailFix

What does the error look like?

  • 401 Unauthorized
  • "message":"authorization required"
  • 403 Forbidden
  • "message":"access forbidden"

Cause 1 of 3

The Authorization header is not in the Bearer form

1Check

SendGrid wants the header Authorization: Bearer followed by the key, with nothing else added. Print what your app really holds: extra characters such as spaces, quotes or a line break around the key would change the header.

node -e "const k=process.env.SENDGRID_API_KEY; console.log(JSON.stringify(k?.slice(0,3)), k?.length)"

2Fix

Load the key as the bare secret string, trim it, and build the header yourself as Bearer plus the key.

const res = await fetch('https://api.sendgrid.com/v3/mail/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRID_API_KEY.trim()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(message),
});

3Verify

Send a request with an empty body. A 400 (bad request) instead of 401 means SendGrid accepted the key; the full curl from the first step should return 202.

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.sendgrid.com/v3/mail/send -H "Authorization: Bearer $SENDGRID_API_KEY" -H "Content-Type: application/json" -d '{}'

Confirmed by twilio.com

Did this fix it?

Cause 2 of 3

The key was deleted, or you copied it wrongly when it was created

1Check

SendGrid shows a key only once, at creation, and rejects calls made with a deleted key. Open Settings, API Keys in the console and see whether a key with that name still exists.

echo "key starts with: ${SENDGRID_API_KEY:0:6}"

2Fix

SendGrid cannot restore a deleted or unknown key. Create a new key, store it in your secret manager at once, and update the environment of every service that used the old one.

# after creating the new key in the console
export SENDGRID_API_KEY='the-new-key'

3Verify

Restart the app so it reads the new value, then send one test mail.

node send-test.js

Confirmed by twilio.com

Did this fix it?

Cause 3 of 3

The key exists but has no permission for sending mail

1Check

A Custom Access key only reaches the endpoints you ticked when you made it. In the API Keys page, open the key and look for Mail Send.

echo 'Console: Settings > API Keys > (key name) > check Mail Send access'

2Fix

Create a new key with Full Access or with Custom Access that includes Mail Send. A key cannot be given more permission than your own user has.

echo 'Console: Create API Key > Custom Access > enable Mail Send'

3Verify

Send the test request from the first step with the new key.

node send-test.js

Confirmed by twilio.com

Did this fix it?

How do I stop it coming back?

  • Give each app its own key with only the permissions it needs, so revoking one key breaks one app.
  • Save a new key straight into your secret store, because the console will not show it again.
  • Keep the key out of source control; a revoked key is also how leaked keys get cleaned up.
  • Trim whitespace when loading keys from files or CI variables.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Email

Django send_mail fails or hangs with an SSL error

smtplib.SMTPException raised from send_mail()

Django has two secure modes that must not be mixed: EMAIL_USE_TLS for explicit TLS (STARTTLS, usually port 587) and EMAIL_USE_SSL for implicit TLS (usually port 465).

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.