Authorization Header

To authenticate, add an Authorization header to your API request containing an API Key.

API Keys

SendGrid’s Web API v3 supports the use of API Keys. API Keys allow you to use another method of authentication separate from your account username and password. API Keys add an additional layer of security for your account and can be assigned specific permissions to limit which areas of your account they may be used to access. API Keys can be generated in your account - visit To use keys, you must set a plain text header named “Authorization” with the contents of the header being “Bearer XXX” where XXX is your API Secret Key.

Example header:

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

On-Behalf of Subuser

The On-Behalf-Of header allows you to make calls for a particular subuser through the parent account; this can be useful for automating bulk updates or administering a subuser without changing authentication in your code. In the header you are passing, you will simply need to add: On-Behalf-Of: subuser_username

This will generate the api call as if it was the subuser account itself making the call. Just make sure you are using the correct subuser username.

When authenticating using the On-Behalf-Of header, you will need to use the API key credentials of the parent account.

Using API Key:

curl -X GET \
   '' \

   -H 'authorization: Bearer API Key' \

   -H 'On-Behalf-Of: subuser_username' \

Please note: The On-Behalf-Of header will not work with the mail.send API.