The CIDR Whitelist is a crucial security feature that allows you to efficiently manage and control IP address access to your systems. By defining specific CIDR blocks, you can ensure that only trusted and authorized networks can interact with your services, thereby enhancing your network security and reducing exposure to unauthorized access.
Use Cases for CIDR Whitelisting
Allow Only Specific Networks
Suppose your application or service is intended to serve users or systems within a particular corporate or regional network. By whitelisting the CIDR ranges associated with that network, you ensure that only requests originating from those specified IP ranges are accepted.
Whitelisted Example: Suppose your organization’s operations are within the 203.0.113.0/24 network. By whitelisting this network:
- Allowed: Any IP from 203.0.113.0 to 203.0.113.255 can access your services.
- Blocked: Any IP not within this range will be denied access.
Blocking Unauthorized Access
By default, any IP address not specified within the whitelist is blocked. This ensures that unknown or potentially malicious actors from different network segments cannot access protected resources.
How to Configure
All requests require authentication via API Key:
'Authorization': 'API_KEY ' + my_api_key
API Endpoints
Base URL: http://api.docdigitizer.com/api/v1
All endpoints listed below should be accessed using the base URL above.
Add List of CIDRs to Whitelist
Use the PUT operation to configure whitelisted CIDR blocks for your account. This process involves sending a request with the CIDR list you wish to grant access.
- Method:
PUT
- Endpoint: Base URL +
/organizations/cidrwhitelist
- Description: Adds a specified list of CIDR blocks to the whitelist for the authenticated customer.
- Authorization: Required (API_KEY)
- Body: Json with "listCIDR" element including the array of CIDR blocks
Important: The source IP from where you're calling this API must belong to one of the CIDR blocks included!
Example Request:
PUT http://api.docdigitizer.com/api/v1/organizations/cidrwhitelist HTTP/1.1
Authorization: API_KEY <my_api_key>
Content-Type: application/json
Body:
{
"listCIDR": ["192.168.0.0/24"]
}
Response
- 200 OK if successfully added.
- 400 Bad Request if parameters are invalid.
- 401 Unauthorized IP.
- 5XX Internal Server Error if an unexpected issue occurs.
Notes
- The list of CIDR blocks must be in valid CIDR notation.
- If this endpoint is not utilized, the default CIDR is 0.0.0.0/0, permitting access from any IP (which effectively disables whitelisting).
Retrieve Whitelisted IPs
Use the GET operation to retrieve the current list of whitelisted IPs associated with your customer account. This operation will provide you with all the CIDR blocks that have been configured to allow access, ensuring you can audit and verify your access controls.
- Method:
GET
- Endpoint: Base URL +
/organizations/cidrwhitelist?mode=list
- Description: Retrieves the list of IP addresses that are currently whitelisted for the authenticated customer account.
Example Request:
GET http://api.docdigitizer.com/api/v1/organizations/cidrwhitelist?mode=list HTTP/1.1
Authorization: API_KEY <my_api_key>
Content-Type: application/json
Response
- 200 OK if the retrieval is successful.
- Response Body Example:
{ "idCustomer": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "listCIDR": [ "192.168.0.0/24" ] }
- Response Body Example:
- 400 Bad Request if parameters are invalid.
- 401 Unauthorized IP.
- 5XX Internal Server Error if an unexpected issue occurs.
Check Whitelisted IP
Use the GET operation with mode=check to check if my current IP is whitelisted.
- Method:
GET
- Endpoint: Base URL +
/organizations/cidrwhitelist?mode=check
- Description: Retrieves information about current IP address, if it's whitelisted or not.
Example Request:
GET http://api.docdigitizer.com/api/v1/organizations/cidrwhitelist?mode=check HTTP/1.1
Authorization: API_KEY <my_api_key>
Content-Type: application/json
Response
- 200 OK if the retrieval is successful.
- Response Body Example:
{ "idCustomer": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "isWhitelisted": true }
- Response Body Example:
- 400 Bad Request if parameters are invalid.
- 401 Unauthorized IP.
- 5XX Internal Server Error if an unexpected issue occurs.
Notes
- Default: 0.0.0.0/0 (allows all IPs) if no whitelist configured
Usage
Once configured, the CIDR Whitelist actively governs access, automatically blocking any IPs not covered by your specified CIDR blocks. Use the platform confidently, knowing unauthorized IPs are restricted from accessing your services.