{ "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.\n\nThere is no limit to the number of IP addresses that you can allow.\n\nIt 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.\n\nSee [**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.**\n\nTo 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.**\n\nEach 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.**\n\nTo 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.\n\nIt 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.**\n\nYou 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.**\n\nWhen 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 `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). 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" } }