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