API keys & authentication

Every request to the SendGrail API authenticates with an API key — a bearer token your application sends on each call.

How authentication works

Pass your key in the Authorization header as a bearer token:

POST /emails HTTP/1.1
Host: api.sendgrail.com
Authorization: Bearer sg_i8CtWNyXYLp7ZXgvFIAucVe2XBz4pCSBjiZiVT87
Content-Type: application/json

A request with a missing, malformed or revoked key is rejected with 401 Unauthorized. There is no other authentication scheme — no cookies, no sessions.

Create a key

1. In the dashboard, go to API keys → Create API key.
2. Set:
   • Name — a label such as Production, Staging or Local.
   • Permission — see Permissions below.
   • Domain — (Sending access keys only) restrict the key to one verified domain, or leave it on All domains.
3. Click Add.

SendGrail shows the full key once — for example sg_i8CtWNyXYLp7ZXgvFIAucVe2XBz4pCSBjiZiVT87. Copy it now.

Keys are shown once

SendGrail stores only a hash of the key, never the key itself. If you lose it, you can't recover it — revoke it and create a new one.

Permissions

Each key has one permission level:

Permission	Can do	Use for
Sending access	Call the send endpoints (POST /v1/emails, POST /v1/emails/batch) only.	Production senders. If the key leaks, the damage is limited to sending email.
Full access	Every API endpoint, including account management.	Trusted internal tooling that needs more than sending.

Default to Sending access. Almost every integration only needs to send email — there's no reason to hand a production sender more power than that.

Domain scoping

Domain scoping is a sub-option of Sending access — Full-access keys always have the run of every verified domain on the team.

For a Sending-access key you choose one of:

• All domains — the key can send from any verified domain on the team.
• A specific domain — the key can only send from addresses on that domain. A send from any other domain fails with a 422 and "This API key is scoped to a different domain.".

Scope keys per domain when you run several products on separate domains and want their credentials isolated, so a leak of the "marketing.com" key can't be used to send from "billing.com".

Storing your key

Read the key from an environment variable or secret manager — never hard-code it, never commit it.

# .env  — excluded from version control
SENDGRAIL_API_KEY=sg_i8CtWNyXYLp7ZXgvFIAucVe2XBz4pCSBjiZiVT87

Use a separate key per environment (production, staging, local). If one leaks, you revoke just that key without disrupting the others.

Rotating a key

To rotate without downtime:

1. Create a new key (e.g. Production (new)).
2. Deploy your application with the new key.
3. Confirm sending still works.
4. Revoke the old key.

This avoids any window where neither key is live.

Revoke a key

Open a key's menu and choose Revoke key, or tick several keys and use the selection bar to revoke them in bulk. You confirm by typing the key's name (or N keys for a bulk revoke), so a revoke can't happen by a stray click. Revocation is immediate and permanent — every request using that key starts returning 401. Revoke a key as soon as you suspect it's been exposed.

What you'll see in the dashboard

The API keys list shows, per key: its name, a short token prefix (enough to recognise it without exposing the secret), its permission and domain scope, when it was last used, and when it was created.

Open a key to see its detail — permission, domain scope, total uses, token prefix, last used, created, and the team member who created it. From there you can edit the key's name, permission or domain scope, or revoke it. The key string itself is never shown again after creation.

Next steps

• Send an email — use your key to send.
• Errors & rate limits — per-key rate limits and 401 details.