openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid IP Access Management API
  summary: IP Twilio SendGrid IP Access Management API allows you to control which
    IP addresses can be used to access your account, either through the SendGrid application
    user interface or the API.
  description: 'IP Twilio SendGrid IP Access Management API allows you to control
    which IP addresses can be used to access your account, either through the SendGrid
    application user interface or the API.


    There is no limit to the number of IP addresses that you can allow.


    It is possible to remove your own IP address from your list of allowed addresses,
    thus blocking your own access to your account. While we are able to restore your
    access, we do require thorough proof of your identify and ownership of your account.
    We take the security of your account very seriously and wish to prevent any ''bad
    actors'' from maliciously gaining access to your account. Your current IP is clearly
    displayed to help prevent you from accidentally removing it from the allowed addresses.


    See [**IP Access Management**](https://docs.sendgrid.com/ui/account-and-settings/ip-access-management)
    for more information.'
  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: ip_access_management
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/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:
  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
  responses:
    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'
    IpAccessManagement500:
      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: IP Access Management
  description: Twilio SendGrid IP Access Management API
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid