openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account API Keys API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  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: account_provisioning
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](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:
  responses:
    GlobalError500:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
    GlobalError404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ApiKeysError400:
      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'
    ApiKeysError403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ApiKeysError404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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
  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
  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