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.
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