Skip to main content

Whitelist Endpoints

Manage IP whitelist entries that are synced to all servers.

List Whitelist​

Get all whitelist entries.

GET /api/v1/whitelist

Query Parameters​

ParameterTypeDescription
searchstringSearch by IP or description
pageintegerPage number (default: 1)
limitintegerItems per page (default: 50, max: 100)

Response​

Success (200):

{
  "whitelist": [
    {
      "id": 1,
      "ip": "10.0.0.0/8",
      "description": "Internal network",
      "created_by": "admin",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "ip": "203.0.113.50",
      "description": "Office IP",
      "created_by": "admin",
      "created_at": "2024-01-05T10:00:00Z"
    }
  ],
  "total": 15,
  "page": 1,
  "limit": 50
}

Example​

curl "https://bloqd.example.com/api/v1/whitelist" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Whitelist Entry​

Get a specific whitelist entry.

GET /api/v1/whitelist/{id}

Path Parameters​

ParameterTypeDescription
idintegerWhitelist entry ID

Response​

Success (200):

{
  "id": 1,
  "ip": "10.0.0.0/8",
  "description": "Internal network",
  "created_by": "admin",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Add Whitelist Entry​

Add an IP or CIDR to the whitelist.

POST /api/v1/whitelist

Request Body​

{
  "ip": "203.0.113.100",
  "description": "Partner API server"
}

Response​

Success (201):

{
  "id": 16,
  "ip": "203.0.113.100",
  "description": "Partner API server",
  "created_by": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}

Example​

curl -X POST "https://bloqd.example.com/api/v1/whitelist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "203.0.113.100",
    "description": "Partner API server"
  }'

Add Multiple Entries​

Add multiple IPs at once.

POST /api/v1/whitelist/bulk

Request Body​

{
  "entries": [
    { "ip": "203.0.113.101", "description": "Server 1" },
    { "ip": "203.0.113.102", "description": "Server 2" },
    { "ip": "203.0.113.103", "description": "Server 3" }
  ]
}

Response​

Success (201):

{
  "added": 3,
  "entries": [
    { "id": 17, "ip": "203.0.113.101" },
    { "id": 18, "ip": "203.0.113.102" },
    { "id": 19, "ip": "203.0.113.103" }
  ]
}

Update Whitelist Entry​

Update an existing whitelist entry.

PATCH /api/v1/whitelist/{id}

Path Parameters​

ParameterTypeDescription
idintegerWhitelist entry ID

Request Body​

{
  "description": "Updated description"
}

Response​

Success (200):

{
  "id": 1,
  "ip": "10.0.0.0/8",
  "description": "Updated description",
  "updated_at": "2024-01-15T10:30:00Z"
}

Delete Whitelist Entry​

Remove an IP from the whitelist.

DELETE /api/v1/whitelist/{id}

Path Parameters​

ParameterTypeDescription
idintegerWhitelist entry ID

Response​

Success (200):

{
  "message": "Whitelist entry deleted"
}

Get Plain Text Whitelist​

Get whitelist as plain text (used by fail2ban).

GET /api/v1/whitelist.txt

Response​

Success (200):

# Bloqd Whitelist
# Generated: 2024-01-15T10:30:00Z
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
203.0.113.50
203.0.113.100

Content-Type: text/plain

Check if IP is Whitelisted​

Check if a specific IP is in the whitelist.

GET /api/v1/whitelist/check/{ip}

Path Parameters​

ParameterTypeDescription
ipstringIP address to check

Response​

Success (200):

{
  "ip": "10.0.0.5",
  "whitelisted": true,
  "matched_entry": {
    "id": 1,
    "ip": "10.0.0.0/8",
    "description": "Internal network"
  }
}

Not Whitelisted:

{
  "ip": "192.168.1.100",
  "whitelisted": false,
  "matched_entry": null
}

Import Whitelist​

Import whitelist entries from file or text.

POST /api/v1/whitelist/import

Request Body​

{
  "format": "plain",
  "content": "10.0.0.0/8\n172.16.0.0/12\n192.168.0.0/16",
  "description_prefix": "Imported"
}

Supported formats: plain, json, csv

Response​

Success (200):

{
  "imported": 3,
  "skipped": 0,
  "errors": []
}

Export Whitelist​

Export whitelist in various formats.

GET /api/v1/whitelist/export

Query Parameters​

ParameterTypeDescription
formatstringplain, json, csv (default: plain)

Response (JSON)​

{
  "whitelist": [
    { "ip": "10.0.0.0/8", "description": "Internal network" },
    { "ip": "203.0.113.50", "description": "Office IP" }
  ],
  "exported_at": "2024-01-15T10:30:00Z"
}

Response (Plain)​

10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
203.0.113.50

Sync Status​

Check whitelist sync status across servers.

GET /api/v1/whitelist/sync-status

Response​

Success (200):

{
  "servers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "web-server-01",
      "last_sync": "2024-01-15T10:25:00Z",
      "sync_status": "synced",
      "entry_count": 15
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "hostname": "web-server-02",
      "last_sync": "2024-01-15T10:20:00Z",
      "sync_status": "synced",
      "entry_count": 15
    }
  ]
}

Force Sync​

Trigger immediate whitelist sync to all servers.

POST /api/v1/whitelist/sync

Request Body (Optional)​

{
  "server_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Response​

Success (200):

{
  "message": "Sync triggered",
  "servers_notified": 5
}