IP Allowlist Management

Overview

The IP Allowlist API provides endpoints for restricting management console access to allowed IP addresses only. It operates in whitelist mode to enhance security.

Required Permissions

Operation	Required Permission
Read	`admin:ip_allowlist:read`
Write	`admin:ip_allowlist:write`

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/ip-allowlist`	Get IP allowlist
GET	`/api/admin/ip-allowlist/:id`	Get IP entry details
POST	`/api/admin/ip-allowlist`	Add IP entry
PATCH	`/api/admin/ip-allowlist/:id`	Update IP entry
DELETE	`/api/admin/ip-allowlist/:id`	Delete IP entry
POST	`/api/admin/ip-allowlist/:id/enable`	Enable entry
POST	`/api/admin/ip-allowlist/:id/disable`	Disable entry
POST	`/api/admin/ip-allowlist/check`	Check IP permission

Get IP Allowlist

Retrieve the IP allowlist.

Endpoint

GET /api/admin/ip-allowlist

Query Parameters

Parameter	Type	Required	Description
`include_disabled`	boolean	-	Include disabled entries (default: false)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/ip-allowlist?include_disabled=true" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "ip_abc123",
      "ip_range": "192.168.1.0/24",
      "description": "Office network",
      "enabled": true,
      "created_at": 1705881600000,
      "updated_at": 1706140800000
    },
    {
      "id": "ip_def456",
      "ip_range": "10.0.0.0/8",
      "description": "VPN network",
      "enabled": true,
      "created_at": 1705968000000,
      "updated_at": null
    },
    {
      "id": "ip_ghi789",
      "ip_range": "203.0.113.50",
      "description": "Remote work - John",
      "enabled": false,
      "created_at": 1706054400000,
      "updated_at": 1706140800000
    }
  ],
  "total": 3,
  "restriction_active": true
}

Get IP Entry Details

Retrieve detailed information for a specified IP entry.

Endpoint

GET /api/admin/ip-allowlist/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Entry ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/ip-allowlist/ip_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "ip_abc123",
  "ip_range": "192.168.1.0/24",
  "description": "Office network",
  "enabled": true,
  "created_by": "admin_xyz789",
  "created_at": 1705881600000,
  "updated_at": 1706140800000
}

Add IP Entry

Add a new IP entry.

Endpoint

POST /api/admin/ip-allowlist

Request Body

Field	Type	Required	Description
`ip_range`	string	✓	IP address or CIDR notation
`description`	string	-	Description
`enabled`	boolean	-	Enable/disable (default: true)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/ip-allowlist" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_range": "192.168.1.0/24",
    "description": "Office network",
    "enabled": true
  }'

Response Example

{
  "id": "ip_abc123",
  "ip_range": "192.168.1.0/24",
  "description": "Office network",
  "enabled": true,
  "created_at": 1706227200000
}

Supported Formats

Format	Example	Description
Single IP	`192.168.1.100`	Single IP address
CIDR	`192.168.1.0/24`	Subnet range
IPv6	`2001:db8::1`	IPv6 address
IPv6 CIDR	`2001:db8::/32`	IPv6 subnet

Update IP Entry

Update an existing IP entry.

Endpoint

PATCH /api/admin/ip-allowlist/:id

Request Body

Field	Type	Required	Description
`ip_range`	string	-	IP address or CIDR notation
`description`	string	-	Description
`enabled`	boolean	-	Enable/disable

Request Example

curl -X PATCH "https://{tenant-domain}/api/admin/ip-allowlist/ip_abc123" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Headquarters office network"
  }'

Response Example

{
  "id": "ip_abc123",
  "ip_range": "192.168.1.0/24",
  "description": "Headquarters office network",
  "enabled": true,
  "updated_at": 1706313600000
}

Delete IP Entry

Delete an IP entry.

Endpoint

DELETE /api/admin/ip-allowlist/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/ip-allowlist/ip_ghi789" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "deleted": true,
  "id": "ip_ghi789"
}

Enable Entry

Enable a disabled IP entry.

Endpoint

POST /api/admin/ip-allowlist/:id/enable

Request Example

curl -X POST "https://{tenant-domain}/api/admin/ip-allowlist/ip_ghi789/enable" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "ip_ghi789",
  "enabled": true,
  "enabled_at": 1706400000000
}

Disable Entry

Disable an IP entry (temporarily disable without deleting).

Endpoint

POST /api/admin/ip-allowlist/:id/disable

Request Example

curl -X POST "https://{tenant-domain}/api/admin/ip-allowlist/ip_ghi789/disable" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "ip_ghi789",
  "enabled": false,
  "disabled_at": 1706486400000
}

Check IP Permission

Check if a specified IP address is allowed.

Endpoint

POST /api/admin/ip-allowlist/check

Request Body

Field	Type	Required	Description
`ip_address`	string	✓	IP address to check

Request Example

curl -X POST "https://{tenant-domain}/api/admin/ip-allowlist/check" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": "192.168.1.100"
  }'

Response Example (Allowed)

{
  "ip_address": "192.168.1.100",
  "allowed": true,
  "matched_entry": {
    "id": "ip_abc123",
    "ip_range": "192.168.1.0/24",
    "description": "Office network"
  },
  "restriction_active": true,
  "total_entries": 5
}

Response Example (Denied)

{
  "ip_address": "203.0.113.200",
  "allowed": false,
  "matched_entry": null,
  "restriction_active": true,
  "total_entries": 5
}

Response Example (No Restriction)

{
  "ip_address": "203.0.113.200",
  "allowed": true,
  "matched_entry": null,
  "restriction_active": false,
  "total_entries": 0
}

Best Practices

Office Networks: Set broadly using CIDR blocks
VPN: Register VPN gateway IP address ranges
Remote Work: Manage with individual IP addresses, disable when no longer needed
Emergency Access: Always keep at least one backup IP enabled