openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account IP Access Management 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: IP Access Management
  description: Twilio SendGrid IP Access Management API
paths:
  /v3/access_settings/activity:
    get:
      operationId: ListAccessActivity
      summary: Retrieve all recent access attempts
      tags:
      - IP Access Management
      description: '**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**'
      parameters:
      - name: limit
        in: query
        description: Limits the number of IPs to return.
        schema:
          type: integer
          default: 20
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    description: An array containing the IPs that recently attempted to access your account.
                    items:
                      type: object
                      properties:
                        allowed:
                          type: boolean
                          description: Indicates if the IP address was granted access to the account.
                        auth_method:
                          type: string
                          description: The authentication method used when attempting access.
                        first_at:
                          type: integer
                          description: A Unix timestamp indicating when the first access attempt was made.
                        ip:
                          type: string
                          description: The IP addressed used during the access attempt.
                        last_at:
                          type: integer
                          description: A Unix timestamp indicating when the most recent access attempt was made
                        location:
                          type: string
                          description: The geographic location from which the access attempt originated.
                      required:
                      - allowed
                      - auth_method
                      - first_at
                      - ip
                      - last_at
                      - location
                required:
                - result
              examples:
                response:
                  value:
                    result:
                    - allowed: false
                      auth_method: Web
                      first_at: 1444087966
                      ip: 1.1.1.1
                      last_at: 1444406672
                      location: Australia
                    - allowed: false
                      auth_method: Web
                      first_at: 1444087505
                      ip: 1.2.3.48
                      last_at: 1444087505
                      location: Mukilteo, Washington
        '401':
          $ref: '#/components/responses/IpAccessManagement401'
        '403':
          $ref: '#/components/responses/IpAccessManagement403'
        '404':
          $ref: '#/components/responses/IpAccessManagement404'
        '500':
          $ref: '#/components/responses/IpAccessManagement500'
  /v3/access_settings/whitelist:
    post:
      operationId: AddIpToAllowList
      summary: Add one or more IPs to the allow list
      tags:
      - IP Access Management
      description: '**This endpoint allows you to add one or more allowed IP addresses.**


        To allow one or more IP addresses, pass them to this endpoint in an array. Once an IP address is added to your allow list, it will be assigned an `id` that can be used to remove the address. You can retrieve the ID associated with an IP using the "Retrieve a list of currently allowed IPs" endpoint.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ips:
                  type: array
                  description: An array containing the IP(s) you want to allow.
                  items:
                    type: object
                    properties:
                      ip:
                        type: string
                        description: An IP address that you want to allow.
                    required:
                    - ip
              required:
              - ips
              example:
                ips:
                - ip: 192.168.1.1
                - ip: 192.*.*.*
                - ip: 192.168.1.3/32
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAccessManagement2xx'
              examples:
                response:
                  value:
                    result:
                    - id: 1
                      ip: 192.168.1.1/32
                      created_at: 1441824715
                      updated_at: 1441824715
                    - id: 2
                      ip: 192.0.0.0/8
                      created_at: 1441824715
                      updated_at: 1441824715
                    - id: 3
                      ip: 192.168.1.3/32
                      created_at: 1441824715
                      updated_at: 1441824715
        '401':
          $ref: '#/components/responses/IpAccessManagement401'
        '403':
          $ref: '#/components/responses/IpAccessManagement403'
        '404':
          $ref: '#/components/responses/IpAccessManagement404'
        '500':
          $ref: '#/components/responses/IpAccessManagement500'
    get:
      operationId: ListAllowedIp
      summary: Retrieve a list of currently allowed IPs
      tags:
      - IP Access Management
      description: '**This endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account.**


        Each IP address returned to you will have `created_at` and `updated_at` dates. Each IP will also be associated with an `id` that can be used to remove the address from your allow list.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAccessManagement2xx'
              examples:
                response:
                  value:
                    result:
                    - id: 1
                      ip: 192.168.1.1/32
                      created_at: 1441824715
                      updated_at: 1441824715
                    - id: 2
                      ip: 192.168.1.2/32
                      created_at: 1441824715
                      updated_at: 1441824715
                    - id: 3
                      ip: 192.168.1.3/32
                      created_at: 1441824715
                      updated_at: 1441824715
        '401':
          $ref: '#/components/responses/IpAccessManagement401'
        '403':
          $ref: '#/components/responses/IpAccessManagement403'
        '404':
          $ref: '#/components/responses/IpAccessManagement404'
        '500':
          $ref: '#/components/responses/IpAccessManagement500'
    delete:
      operationId: DeleteAllowedIps
      summary: Remove one or more IPs from the allow list
      tags:
      - IP Access Management
      description: '**This endpoint allows you to remove one or more IP addresses from your list of allowed addresses.**


        To remove one or more IP addresses, pass this endpoint an array containing the ID(s) associated with the IP(s) you intend to remove. You can retrieve the IDs associated with your allowed IP addresses using the "Retrieve a list of currently allowed IPs" endpoint.


        It is possible to remove your own IP address, which will block access to your account. You will need to submit a [support ticket](https://sendgrid.com/docs/ui/account-and-settings/support/) if this happens. For this reason, it is important to double check that you are removing only the IPs you intend to remove when using this endpoint.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  description: An array of the IDs of the IP address that you want to remove from your allow list.
                  items:
                    type: integer
              example:
                ids:
                - 1
                - 2
                - 3
      responses:
        '204':
          description: ''
        '401':
          $ref: '#/components/responses/IpAccessManagement401'
        '403':
          $ref: '#/components/responses/IpAccessManagement403'
        '404':
          $ref: '#/components/responses/IpAccessManagement404'
        '500':
          $ref: '#/components/responses/IpAccessManagement500'
  /v3/access_settings/whitelist/{rule_id}:
    parameters:
    - name: rule_id
      in: path
      description: The ID of the allowed IP address that you want to retrieve.
      required: true
      schema:
        type: string
    get:
      operationId: GetAllowedIp
      summary: Retrieve a specific allowed IP
      tags:
      - IP Access Management
      description: '**This endpoint allows you to retreive a specific IP address that has been allowed to access your account.**


        You must include the ID for the specific IP address you want to retrieve in your call. You can retrieve the IDs associated with your allowed IP addresses using the "Retrieve a  list of currently allowed IPs" endpoint.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAccessManagement2xx'
              examples:
                response:
                  value:
                    result:
                    - id: 1
                      ip: 192.168.1.1
                      created_at: 1441824715
                      updated_at: 1441824715
    delete:
      operationId: DeleteAllowedIp
      summary: Remove a specific IP from the allowed list
      tags:
      - IP Access Management
      description: '**This endpoint allows you to remove a specific IP address from your list of allowed addresses.**


        When removing a specific IP address from your list, you must include the ID in your call.  You can retrieve the IDs associated with your allowed IP addresses using the "Retrieve a list of currently allowed IPs" endpoint.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
components:
  responses:
    IpAccessManagement500:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
    IpAccessManagement401:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    IpAccessManagement403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    IpAccessManagement404:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    IpAccessManagement2xx:
      title: IP Access Response
      type: object
      properties:
        result:
          type: array
          description: An array listing one or more of your allowed IPs.
          items:
            type: object
            properties:
              id:
                type: integer
                description: The ID of the allowed IP.
              ip:
                type: string
                description: The allowed IP.
              created_at:
                type: integer
                description: A Unix timestamp indicating when the IP was added to the allow list.
              updated_at:
                type: integer
                description: A Unix timestamp indicating when the IPs allow status was most recently updated.
      example:
        result:
        - id: 1
          ip: 192.168.1.1/32
          created_at: 1441824715
          updated_at: 1441824715
        - id: 2
          ip: 192.0.0.0/8
          created_at: 1441824715
          updated_at: 1441824715
        - id: 3
          ip: 192.168.1.3/32
          created_at: 1441824715
          updated_at: 1441824715
    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
  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