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"
  ]
}