Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Upgrade your authentication method to API keys


(error)

Danger

Two-Factor Authentication is required as of Q4 2020, and all Twilio SendGrid API endpoints will reject new API requests and SMTP configurations made with a username and password via Basic Authentication.


Am I Using Basic Authentication with Username and Password?

am-i-using-basic-authentication-with-username-and-password page anchor
  • 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?

why-should-i-use-api-keys-for-authentication page anchor
(warning)

Warning

Twilio SendGrid API keys are 69 characters long. We are unable to make exceptions for third-party infrastructure that is unable to support a key of 69 characters.

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(link takes you to an external page). To learn more about the principle of least privilege, see our Twilio blog post(link takes you to an external page) and OWASP's article on Access Control(link takes you to an external page).


Tips for upgrading to API Keys

tips-for-upgrading-to-api-keys page anchor
  • 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

upgrade-to-api-keys-for-your-api-endpoint-requests page anchor

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.

Upgrade to API Keys for your SMTP integration

upgrade-to-api-keys-for-your-smtp-integration page anchor
  1. Generate API Keys in the SendGrid UI(link takes you to an external page) 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.

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

(information)

Info

When submitting base64 encoded API key values, be sure you have not included any newline or whitespace characters by accident. This can happen when copying the encoded key from an environment that line wraps output. SMTP is a line-oriented protocol, and linefeed characters will prevent you from authenticating successfully.

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

check-for-api-rejections page anchor

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

Error message for API calls

error-message-for-api-calls page anchor

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(link takes you to an external page)

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(link takes you to an external page)

For more information on how to secure your Twilio SendGrid account visit this blog post(link takes you to an external page).


Rate this page: