API Keys

API Keys

このエンドポイントはWeb API、SMTPで使用される認証情報を作成するための機能です。

API Keys management

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

全APIキー一覧の取得。

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]

このエンドポイントはパーミッションが割り当てられた新しいAPIキーを作成します。リクエストボディのJSON内でname プロパティは必須です。作成可能な最大数に達すると403が返ります。また、APIキーの権限を制限するためにscopesを指定することができます。scopesを指定しない場合、親アカウントと同じ権限がAPIキーに割り当てられます。スコープのリストについてはAPIキーパーミッションリストを参照してください。

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

Get an existing API Key [GET]

APIキーを取得します。APIキーに割り当てることのできるパーミッションのリストについては、APIキーパーミッションリストを参照してください。

指定したapi_key_idが存在しない場合、HTTPステータス404が返ります。

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]

APIキーの削除。APIキーが削除されると認証は失敗します。認証が失敗するようになるまで若干の遅れがあります。APIキーに割り当てることのできるパーミッションのリストについては、APIキーパーミッションリストを参照してください。

API Key IDが存在しない場合、404が返ります。

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]

APIキー名の更新。リクエストボディのJSONにはnameプロパティが必須です。APIキーに割り当てることのできるパーミッションのリストについては、APIキーパーミッションリストを参照してください。

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]

APIキー名およびスコープの更新。リクエストボディのJSONにはnameプロパティが必須です。APIキーに割り当てることのできるパーミッションのリストについては、APIキーパーミッションリストを参照してください。

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キーの利用方法

Web APIのHTTP認証には"Bearer"スキーマを利用します。 認証に失敗すると401が返ります。

Authentication [GET]

Request

1

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

Authorization: Bearer SG.xxxxxxxx.yyyyyyyy

Response

1

HTTP/1.1 401

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