Upgrade your authentication method to API keys

Am I Using Basic Authentication with Username and Password?

• If SMTP: Check the username you're using to authenticate. If it's the word "apikey" then you're using an API Key. If it's not, then you're using username and password authentication.
• If V3: If you're using the most recent version of our open sourced libraries and followed the documentation, you should already be using API keys. If you aren't using our libraries, check the Authorization header on your API calls. If you see the word "Bearer" - you're good. If you see the word "Basic" you're using username and password.
• If V2 non-mail send: You're using username and passwords.
• If Premier 50M and below package: Use the Email Activity API to identify mail/send API Key usage. If the api_key_id parameter is empty, you will need to upgrade your authentication.

Why should I use API Keys for authentication?

Using your account username and password for authentication is less secure than using an API Key. API Keys are preferred because you can limit permissions for API Keys and revoke them at any time. We recommend applying the principle of least privilege, using limited API Key permission to only provide access to what is needed for that request for maximum security.

For more about protecting your account, see our blog post, 7 Best Practices to Protect your Twilio SendGrid Account and Sending Reputation. To learn more about the principle of least privilege, see our Twilio blog post and OWASP's article on Access Control.

Tips for upgrading to API Keys

• Prioritize upgrading your authentication method to API Keys for your mail/send endpoints first
• Store your API Keys in an environment variable
• Test these changes in a staging environment before rolling out to your production environment

Upgrade to API Keys for your API endpoint requests

Follow these steps to identify and replace your authentication method to API Keys and then implement 2FA for enhanced security.

1. Identify where you are storing your username and password credentials for basic authentication. Your credentials could be stored in environment variables or hard coded depending on how you integrated.
2. Generate API Keys in the SendGrid UI or programmatically with the least privileged permissions required for each of the endpoints you will be updating. For more information, see API Key Permissions.
3. Replace your username and password credentials with API Keys.

• For v3 API: Follow these instructions.
• For v2: Follow these instructions.

Upgrade to API Keys for your SMTP integration

1. Generate API Keys in the SendGrid UI or programmatically with the least privileged permissions required for each of the endpoints you will be updating. For more information, see API Key Permissions. To send email only, your API key will require Mail Send > Full Access permissions.
2. To use your API key with the SMTP integration, you must set your username to the string, apikey. Your password will be the API key you generated in the previous step.

user_name: "apikey"
password: <Your API Key>

Once the previous steps are completed, enable Two-Factor Authentication for all of your users, including subusers and teammates.

If you are new to our SMTP integration, you will find more integration instructions at Integrating with the SMTP API.

Check for API rejections

After enabling 2FA monitor your API calls for rejections related to continued use of username and password authentication.

Error message for API calls:

invalid authentication method - declined because you are using basic authentication with 2FA enabled. to fix, update to using an API key or disable 2FA and switch to using IP Access Management for security. For more information, see https://sendgrid.com/docs/for-developers/sending-email/authentication/#basic-authentication

Error message for SMTP:

SMTP error message is: 535 Authentication failed: Basic authentication is not allowed with 2FA enabled. To fix, see https://sendgrid.com/docs/for-developers/sending-email/authentication/#basic-authentication

For more information on how to secure your Twilio SendGrid account visit this blog post.