The Twilio SendGrid API Keys API allows you manage your API keys and their settings. Your application, mail client, or website can all use API keys to authenticate access to SendGrid services. To create your initial SendGrid API Key, you should use the [SendGrid application user interface](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid API Keys API
summary: The Twilio SendGrid API Keys API allows you manage your API keys and their
settings. Your application, mail client, or website can all use API keys to authenticate
access to SendGrid services.
description: 'The Twilio SendGrid API Keys API allows you manage your API keys and
their settings. Your application, mail client, or website can all use API keys
to authenticate access to SendGrid services.
To create your initial SendGrid API Key, you should use the [SendGrid application
user interface](https://app.sendgrid.com/settings/api_keys). Once you have created
a first key with scopes to manage additional API keys, you can use this API for
all other key management.'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: api_keys
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
paths:
/v3/api_keys:
post:
operationId: CreateApiKey
summary: Create API keys
tags:
- API Keys
description: '**This endpoint allows you to create a new API Key for the user.**
To create your initial SendGrid API Key, you should [use the SendGrid App](https://app.sendgrid.com/settings/api_keys).
Once you have created a first key with scopes to manage additional API keys,
you can use this API for all other key management.
A JSON request body containing a `name` property is required when making requests
to this endpoint. If the number of maximum keys, 100, is reached, a `403`
status will be returned.
Though the `name` field is required, it does not need to be unique. A unique
API key ID will be generated for each key you create and returned in the response
body.
It is not necessary to pass a `scopes` field to the API when creating a key,
but you should be aware that omitting the `scopes` field from your request
will create a key with "Full Access" permissions by default.
See the [API Key Permissions List](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization)
for all available scopes. An API key''s scopes can be updated after creation
using the "Update API keys" endpoint.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name you will use to describe this API Key.
scopes:
type: array
description: The individual permissions that you are giving to this
API Key.
items:
type: string
required:
- name
example:
name: My API Key
scopes:
- mail.send
- alerts.create
- alerts.read
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
api_key:
type: string
api_key_id:
type: string
name:
type: string
scopes:
type: array
items:
type: string
examples:
response:
value:
api_key: SG.xxxxxxxx.yyyyyyyy
api_key_id: xxxxxxxx
name: My API Key
scopes:
- mail.send
- alerts.create
- alerts.read
'400':
$ref: '#/components/responses/ApiKeysError400'
'401':
$ref: '#/components/responses/GlobalError401'
'403':
$ref: '#/components/responses/ApiKeysError403'
'404':
$ref: '#/components/responses/ApiKeysError404'
'500':
$ref: '#/components/responses/GlobalError500'
get:
operationId: ListApiKey
summary: Retrieve all API Keys belonging to the authenticated user
tags:
- API Keys
description: '**This endpoint allows you to retrieve all API Keys that belong
to the authenticated user.**
A successful response from this API will include all available API keys''
names and IDs.
For security reasons, there is not a way to retrieve the key itself after
it''s created. If you lose your API key, you must create a new one. Only the
"Create API keys" endpoint will return a key to you and only at the time of
creation.
An `api_key_id` can be used to update or delete the key, as well as retrieve
the key''s details, such as its scopes.'
parameters:
- name: limit
in: query
schema:
type: integer
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ApiKeyResponse'
examples:
response:
value:
result:
- name: API Key Name
api_key_id: some-apikey-id
- name: API Key Name 2
api_key_id: another-apikey-id
'401':
$ref: '#/components/responses/GlobalError401'
'403':
$ref: '#/components/responses/GlobalError403'
'404':
$ref: '#/components/responses/GlobalError404'
'500':
$ref: '#/components/responses/GlobalError500'
/v3/api_keys/{api_key_id}:
parameters:
- name: api_key_id
in: path
description: ''
required: true
schema:
type: string
get:
operationId: GetApiKey
summary: Retrieve an existing API Key
tags:
- API Keys
description: '**This endpoint allows you to retrieve a single API key using
an `api_key_id`.**
The endpoint will return a key''s name, ID, and scopes. If the API Key ID
does not, exist a `404` status will be returned.
See the [API Key Permissions List](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization)
for all available scopes. An API key''s scopes can be updated after creation
using the "Update API keys" endpoint.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ApiKeyScopesResponse'
examples:
response:
value:
result:
- name: API Key Name
api_key_id: some-apikey-id
- name: API Key Name 2
api_key_id: another-apikey-id
'400':
$ref: '#/components/responses/ApiKeysError400'
'401':
$ref: '#/components/responses/GlobalError401'
'403':
$ref: '#/components/responses/ApiKeysError403'
'404':
$ref: '#/components/responses/ApiKeysError404'
'500':
$ref: '#/components/responses/GlobalError500'
patch:
operationId: UpdateApiKeyName
summary: Update API key name
tags:
- API Keys
description: '**This endpoint allows you to update the name of an existing API
Key.**
You must pass this endpoint a JSON request body with a `name` property, which
will be used to rename the key associated with the `api_key_id` passed in
the URL.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The new name of the API Key.
required:
- name
example:
name: A New Hope
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
examples:
response:
value:
api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA
name: A New Hope
'400':
$ref: '#/components/responses/ApiKeysError400'
'401':
$ref: '#/components/responses/GlobalError401'
'403':
$ref: '#/components/responses/GlobalError403'
'404':
$ref: '#/components/responses/GlobalError404'
'500':
$ref: '#/components/responses/GlobalError500'
put:
operationId: UpdateApiKey
summary: Update API key name and scopes
tags:
- API Keys
description: '**This endpoint allows you to update the name and scopes of a
given API key.**
You must pass this endpoint a JSON request body with a `name` field and a
`scopes` array containing at least one scope. The `name` and `scopes` fields
will be used to update the key associated with the `api_key_id` in the request
URL.
If you need to update a key''s scopes only, pass the `name` field with the
key''s existing name; the `name` will not be modified. If you need to update
a key''s name only, use the "Update API key name" endpoint.
See the [API Key Permissions List](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization)
for all available scopes.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
scopes:
type: array
items:
type: string
required:
- name
example:
name: Profiles key
scopes:
- user.profile.read
- user.profile.update
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
examples:
response:
value:
api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA
name: Profiles Key
scopes:
- user.profile.read
- user.profile.update
'400':
$ref: '#/components/responses/ApiKeysError400'
'401':
$ref: '#/components/responses/GlobalError401'
'403':
$ref: '#/components/responses/GlobalError403'
'404':
$ref: '#/components/responses/GlobalError404'
'500':
$ref: '#/components/responses/GlobalError500'
delete:
operationId: DeleteApiKey
summary: Delete API keys
tags:
- API Keys
description: '**This endpoint allows you to revoke an existing API Key using
an `api_key_id`**
Authentications using a revoked API Key will fail after after some small propogation
delay. If the API Key ID does not exist, a `404` status will be returned.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'204':
description: ''
'400':
$ref: '#/components/responses/ApiKeysError400'
'401':
$ref: '#/components/responses/GlobalError401'
'403':
$ref: '#/components/responses/GlobalError403'
'404':
$ref: '#/components/responses/GlobalError404'
'500':
$ref: '#/components/responses/GlobalError500'
components:
schemas:
ApiKeyResponse:
title: API Key Name and ID
type: object
properties:
api_key_id:
type: string
description: 'The ID of your API Key. '
name:
type: string
description: The name of your API Key.
example:
api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA
name: Mail Send
ApiKeyScopesResponse:
title: API Key Name, ID, and Scopes
example:
api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA
name: Mail Send
scopes:
- mail.send
- mail.batch.create
- mail.batch.read
- mail.batch.update
- mail.batch.delete
- user.scheduled_sends.create
- user.scheduled_sends.read
- user.scheduled_sends.update
- user.scheduled_sends.delete
- sender_verification_eligible
- sender_verification_legacy
- 2fa_required
type: object
properties:
scopes:
type: array
description: The permissions this API Key has access to.
items:
type: string
api_key_id:
type: string
description: 'The ID of your API Key. '
name:
type: string
description: The name of your API Key.
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: An error message.
field:
description: When applicable, this property value will be the field
that generated the error.
nullable: true
type: string
help:
type: object
description: When applicable, this property value will be helper text
or a link to documentation to help you troubleshoot the error.
id:
type: string
description: When applicable, this property value will be an error ID.
example:
errors:
- field: field_name
message: error message
responses:
ApiKeysError400:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ApiKeysError403:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ApiKeysError404:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
GlobalError401:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
GlobalError403:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
GlobalError404:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
GlobalError500:
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
parameters:
OnBehalfOf:
name: on-behalf-of
in: header
description: 'The `on-behalf-of` header allows you to make API calls from a
parent account on behalf of the parent''s Subusers or customer accounts. You
will use the parent account''s API key when using this header. When making
a call on behalf of a customer account, the property value should be "account-id"
followed by the customer account''s ID (e.g., `on-behalf-of: account-id <account-id>`).
When making a call on behalf of a Subuser, the property value should be the
Subuser''s username (e.g., `on-behalf-of: <subuser-username>`). See [**On
Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of)
for more information.'
required: false
schema:
type: string
examples: {}
requestBodies: {}
headers: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Twilio SendGrid requires you to authenticate with its APIs using
an API key. The API key must be sent as a bearer token in the Authorization
header.
tags:
- name: API Keys
description: Twilio SendGrid API Keys API.
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid