SendGrid 401 "authorization required" (bad API key) in CI

By Daniel Zoghalchali·Latchkey

SendGrid returns HTTP 401 with {"errors":[{"message":"authorization required"}]} when the Authorization header is missing or does not carry a valid API key. In CI the SENDGRID_API_KEY secret is usually empty, revoked, or sent without the Bearer prefix.

What this error means

A build-notification email step calling the SendGrid v3 API gets HTTP 401 with authorization required. No email is sent.

< HTTP/2 401
{"errors":[{"message":"authorization required","field":null,"help":null}]}

Common causes

The API key is empty or not injected

The step reads a secret that is unset or misnamed, so an anonymous request is sent and rejected.

Missing Bearer prefix or a revoked key

Sending the raw key without Bearer , or using a key that was deleted or rotated, yields 401.

How to fix it

Send a valid Bearer key

1. Create a Mail Send API key in SendGrid.
2. Store it as the SENDGRID_API_KEY secret.
3. Send it as Authorization: Bearer $SENDGRID_API_KEY.

curl -sS -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @mail.json

Reference the secret in the step env

Expose the key through the step environment from the correct secret name.

- name: Email CI result
  env:
    SENDGRID_API_KEY: ${{ secrets.SENDGRID_API_KEY }}
  run: ./scripts/email.sh

How to prevent it

• Grant the key only Mail Send scope and store it in CI secrets.
• Rotate the key and secret together.
• Always send the Bearer prefix in the Authorization header.

Frequently asked questions

Related guides

References

• GitHub Actions documentation