SendGrid supports both API key and basic authentication, depending on the functionality you are using. On top of API key authentication, SendGrid offers two-factor authentication (2FA) to improve security.

Authenticate to the SendGrid API by creating an API Key in the Settings section of the SendGrid UI.

SendGrid recommends API Keys because they are a secure way to talk to the SendGrid API that is separate from your username and password. If your API key gets compromised in any way, it is easy to delete and create a new one and update your environment variables with the new key. An API key permissions can be set to provide access to different functions of your account, without providing full access to your account as a whole.

To use the API Key, have a header with a key Authorization and a value of Bearer <Your-API-Key-Here>, where you replace <Your-API-Key-Here> with the API Key that you created in the UI.

SendGrid supports API keys with the SMTP API, the /v3/ API (except the methods to create API keys), and with the /api/mail.send.json and /api/mail.send.xml.

Example header:

Authorization: Bearer Your.API.Key-HERE
curl -X "GET" "" -H "Authorization: Bearer Your.API.Key-HERE" -H "Content-Type: application/json"

Basic authentication

SendGrid does not recommend using basic authentication. However, if you are using our legacy v2 API, you have to use basic authentication to connect.

Using basic authentication is not as secure as using an API key because it uses your username and password credentials, allowing full access to your account. So, if your credentials get compromised, (like if you accidentally commit them to GitHub), it is more difficult to regain the security of your account.

It is not possible to enable Two-factor authentication when using basic authentication, so if you do need to use basic authentication we highly recommend that you set up IP Access Management for improved security.

To use basic authentication, have a header with a key Authorization, and a value of Basic <encoded-user-name><encoded-password>, where you replace <encoded-user-name><encoded-password> with your URL encoded username and password.

You have to use basic authentication if you are using v2 of the API.

Two-factor authentication

SendGrid recommends enabling two-factor authentication (2FA) for all users. For more information about setting up 2FA, see Two-factor authentication.

It is not possible to use basic authentication for users, subusers, or teammates that enable 2FA.

See a mistake? Edit this page