API Keys

API Keys allow you to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API, the v3 Mail Send endpoint, and the v2 Mail Send endpoint.

There is a limit of 100 API Keys per account.

API Keys management

List all API Keys belonging to the authenticated user [GET]

Request

1
GET https://api.sendgrid.com/v3/api_keys HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 200
{
  "result": [
    {
      "name": "A New Hope",
      "api_key_id": "xxxxxxxx"
    }
  ]
}

Generate a new API Key for the authenticated user [POST]

This will create a new random API Key for the user with permissions assigned. A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. Optionally, you can specify "scopes" to limit what permissions an API Key is given. If no API Key is provided, it will assign all of the parent account's assignable scopes to the API Key. For a list of all scopes, please look at the API Keys Permissions List

Request

1
POST https://api.sendgrid.com/v3/api_keys HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
{
  "name": "My API Key",
  "scopes": [
    "mail.send",
    "alerts.create",
    "alerts.read"
  ]
}

Response

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 201
{
  "api_key": "SG.xxxxxxxx.yyyyyyyy",
  "api_key_id": "xxxxxxxx",
  "name": "My API Key",
  "scopes": [
    "mail.send",
    "alerts.create",
    "alerts.read"
  ]
}

Request

1
POST https://api.sendgrid.com/v3/api_keys HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 400
{
  "errors": [
    {
      "field": "name",
      "message": "missing required argument"
    }
  ]
}

Request

1
POST https://api.sendgrid.com/v3/api_keys HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 403
{
  "errors": [
    {
      "field": null,
      "message": "Cannot create more than 100 API Keys"
    }
  ]
}

There is a limit of 100 API Keys per account.

Get an existing API Key [GET]

Retrieve a single api key. For a list of permissions that can be assigned to API Keys, please see our API Keys Permissions List.

If the API Key ID does not exist an HTTP 404 will be returned.

Request

1
GET https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200
{
  "api_key_id": "xxxxxxxx",
  "name": "My API Key",
  "scopes": [
    "mail.send",
    "alerts.create",
    "alerts.read"
  ]
}

Request

1
GET https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 404
{
  "errors": [
    {
      "field": null,
      "message": "unable to find API Key"
    }
  ]
}

Revoke an existing API Key [DELETE]

Authentications using this API Key will fail after this request is made, with some small propagation delay. For a list of permissions that can be assigned to API Keys, please see our API Keys Permissions List.

If the API Key ID does not exist an HTTP 404 will be returned.

Request

1
DELETE https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1

Response

1
HTTP/1.1 204

Request

1
DELETE https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 404
{
  "errors": [
    {
      "field": null,
      "message": "unable to find API Key for deletion"
    }
  ]
}

Update the name of an existing API Key [PATCH]

A JSON request body with a "name" property is required. For a list of permissions that can be assigned to API Keys, please see our API Keys Permissions List.

Request

1
PATCH https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1
Request Body
1
2
3
{
  "name": "A New Hope"
}

Response

1
2
3
4
5
HTTP/1.1 200
{
  "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
  "name": "A New Hope"
}

Update the name & scopes of an API Key [PUT]

A JSON request body with a "name" property is required. Most provide the list of all the scopes an api key should have. For a list of permissions that can be assigned to API Keys, please see our API Keys Permissions List.

Request

1
PUT https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1
Request Body
1
2
3
4
5
6
7
{
  "name": "A New Hope",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ]
}

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 200
{
  "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA",
  "name": "A New Hope",
  "scopes": [
    "user.profile.read",
    "user.profile.update"
  ]
}

Request

1
PUT https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 400
{
  "errors": [
    {
      "field": null,
      "message": "expected JSON request body with 'name' property"
    }
  ]
}

Request

1
PUT https://api.sendgrid.com/v3/api_keys/{api_key_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 404
{
  "errors": [
    {
      "field": null,
      "message": "unable to find API Key to update"
    }
  ]
}

API Key usage

The API Keys feature adds a new "Bearer" scheme for HTTP authentication for both v3 WebAPI and the mail.send API.This is an example. This endpoint does not exist.Returns HTTP 401 if authentication fails.

Authentication [GET]

Request

1
GET https://api.sendgrid.com/v3/resource HTTP/1.1
Request Header
1
Authorization: Bearer SG.xxxxxxxx.yyyyyyyy

Response

1
HTTP/1.1 401
Returns HTTP 400 if authentication fails.

HTTP Authentication [GET]

Request

1
GET https://api.sendgrid.com/v3/api/mail.send.json HTTP/1.1
Request Header
1
Authorization: Bearer SG.xxxxxxxx.yyyyyyyy

Response

1
2
3
4
HTTP/1.1 200
{
  "message": "success"
}

Request

1
GET https://api.sendgrid.com/v3/api/mail.send.json HTTP/1.1

Response

1
2
3
4
5
6
7
HTTP/1.1 400
{
  "message": "error",
  "errors": [
    "invalid API Key"
  ]
}
Please note that certain scopes must be added via the API using basic authorization with the parent account credentials. This is because there are less permissions displayed in the UI's API keys settings than what actually exist in the API Key Permissions List. This list contains more permissions than what can be added to your API key via our UI.
Currently, when you create a key and give it access to everything, it excludes various permissions. The best way to see what permissions your key has is by making this call using the API key in question to make the call. For the user profile call you're attempting to make, you will need to make sure you have these permissions:"scopes": [   "user.account.read",   "user.profile.read", ] Afterwards, to give your API key these extra permissions, you will need to make this call (https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/index.html#Update-the-name-amp-scopes-of...) * You can add basic authorization to your API call yourself by base64 encoding your parent account username and password like this: username:password and adding it to your Authorization header as Basic. We go into a little more detail on this here (https://sendgrid.com/blog/magic-behind-basic-http-authentication/).
 * Or you can use a rest client like Postman (https://www.getpostman.com/) or Paw (https://paw.cloud/), where you can select to Authenticate with basic auth (your SendGrid parent account username and password) then update the request to add your parent account credentials encoded into the headers.
 When making the call, it is important to add all of the scopes you want for the API key to have. If you make the call, and just list "categories.read" as the scopes, you will then have a key with only the "categories.read" scope. So make sure to list everything you get from the get existing key call (https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/index.html#Get-an-existing-API-Key-GET) in addition to the new scopes you want to add.