SendGrid API Keys API

openapi: 3.2.0
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. 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
security:
- BearerAuth: []
tags:
- name: API Keys
  description: Twilio SendGrid API Keys API.
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. 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 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 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 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:
  responses:
    GlobalError500:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
    ApiKeysError400:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ApiKeysError404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    GlobalError403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    GlobalError401:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    GlobalError404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ApiKeysError403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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
  schemas:
    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
    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
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid