IP Restrictions API
The IP Restrictions API lets your scripts and tools view and change a workspace's IP allowlist, and turn IP restrictions on or off, using an API key instead of signing in. It offers the same controls as the IP Restrictions page in the Customer Management Portal.
Note: The API is available for DashboardFox Cloud only. It is not part of the self-hosted edition.
Before you start
You need three things:
An API key with the right permissions. An Agency Owner creates it under Agency Settings, on the API Keys tab. See Creating and Managing API Keys.
The API address for your region. A key only works in the region where it was created.
The workspace ID of each workspace you want to manage. It is shown next to each workspace when you create a key, and in the portal address when a workspace is open (for example
.../workspace/87/ip-restrictions). A key with Workspaces: read can also list them.
Region | API address |
|---|---|
United States |
|
Europe |
|
The examples in this article use the US address and workspace ID 87.
Requests and responses
Authentication. Send your key in the Authorization header of every request:
Authorization: Bearer dfx_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Never put the key in the URL.
Request bodies. Send JSON with the header Content-Type: application/json. Bodies are limited to 10 KB.
Responses. Every response is JSON. Errors always have the same shape, with a machine-readable code and a readable message:
{"error": {"code": "insufficient_scope", "message": "This API key needs the \"ip_restrictions:admin\" permission."}}
Limits.
Limit | Value | When exceeded |
|---|---|---|
Requests per API key | 60 per minute |
|
Requests per client IP | 120 per minute |
|
Changes to one workspace's IP restrictions | 20 per hour, all keys combined |
|
Only requests that actually change something count toward the hourly change limit. Reading data, or sending an IP that is already set, never uses it up.
Note: The API is for server-to-server use. Browsers cannot call it.
Endpoints at a glance
Paths are relative to your region's API address.
Method | Path | Permission needed | What it does |
|---|---|---|---|
GET |
| Any valid key | Describes the key and the IP address the server sees |
GET |
| Workspaces: read | Lists the workspaces the key can access |
GET |
| IP restrictions: read | Shows whether restrictions are on and lists allowlist entries |
POST |
| IP restrictions: write | Adds an allowlist entry |
PUT |
| IP restrictions: write | Creates or updates the entry with this label |
DELETE |
| IP restrictions: write | Removes an allowlist entry |
PUT |
| IP restrictions: admin | Turns IP restrictions on or off |
IP restrictions: write also allows the read endpoint, and IP restrictions: admin allows everything in the table except listing workspaces.
Account endpoints
Check your key: GET /whoami
Returns the key's name, permissions, workspaces and expiry, plus the IP address the server sees for your request. Works with any valid key, so it is the quickest way to test a new key.
curl https://my.dashboardfox.app/api/v1/whoami \ -H "Authorization: Bearer $DFX_KEY"
{ "key": { "name": "Office IP updater", "prefix": "dfx_0a26b993ea", "scopes": ["ip_restrictions:write"], "all_workspaces": false, "workspace_ids": [87], "expires_at": "2027-02-16T13:47:17.527Z" }, "agency": {"id": "agency-23b6395d9b8c6d4a", "name": "Example Agency"}, "region": "US", "client_ip": "203.0.113.7", "client_ip_version": 4}
client_ip is the address an auto value would use (see IP address rules).
List workspaces: GET /workspaces
Lists the workspaces the key can access. Requires Workspaces: read.
curl https://my.dashboardfox.app/api/v1/workspaces \ -H "Authorization: Bearer $DFX_KEY"
{ "workspaces": [ {"id": 87, "name": "Acme Reporting", "slug": "acmereporting", "status": "active", "ip_restriction_enabled": true} ]}
IP restriction endpoints
Changes are saved immediately. When IP restrictions are on, they take effect on the workspace within about a minute, and the response includes "sync_queued": true. When restrictions are off, entries are saved but not enforced until restrictions are turned on.
View status and entries: GET /workspaces/{id}/ip-restrictions
Requires IP restrictions: read.
curl https://my.dashboardfox.app/api/v1/workspaces/87/ip-restrictions \ -H "Authorization: Bearer $DFX_KEY"
{ "enabled": true, "entries": [ {"id": 5, "ip_cidr": "203.0.113.7", "label": "office", "created_at": "2026-11-18T13:49:18.386Z", "updated_at": "2026-11-18T13:55:43.690Z"} ]}
Add an entry: POST /workspaces/{id}/ip-restrictions/entries
Requires IP restrictions: write.
Field | Required | Description |
|---|---|---|
| Yes | An IP address, a range, or |
| No | A name for the entry, up to 100 characters |
curl -X POST https://my.dashboardfox.app/api/v1/workspaces/87/ip-restrictions/entries \ -H "Authorization: Bearer $DFX_KEY" -H "Content-Type: application/json" \ -d '{"ip_cidr": "198.51.100.0/24", "label": "branch office"}'
Returns 201 with the new entry. If the address is already on the list, returns 409 ip_exists.
Set an entry by label: PUT /workspaces/{id}/ip-restrictions/entries/by-label/{label}
Requires IP restrictions: write. Creates the entry with this label, or changes its address if it already exists. If the address is already set, nothing is changed and the call does not count toward the change limit, so it is safe to send repeatedly.
Field | Required | Description |
|---|---|---|
| Yes | An IP address, a range, |
curl -X PUT https://my.dashboardfox.app/api/v1/workspaces/87/ip-restrictions/entries/by-label/office \ -H "Authorization: Bearer $DFX_KEY" -H "Content-Type: application/json" \ -d '{"ip_cidr": "auto"}'
{ "entry": {"id": 5, "ip_cidr": "203.0.113.7", "label": "office", "created_at": "2026-11-18T13:49:18.386Z", "updated_at": "2026-11-18T13:55:43.690Z"}, "created": false, "changed": true, "previous_ip_cidr": "203.0.113.9", "sync_queued": true}
Result | Status |
|
|
|---|---|---|---|
New entry created | 201 | true | true |
Address updated | 200 | false | true |
Already set, nothing to do | 200 | false | false |
Labels must start with a letter or number and may contain letters, numbers, spaces, dots, dashes and underscores. Encode spaces in the URL as %20.
Remove an entry: DELETE /workspaces/{id}/ip-restrictions/entries/{entryId}
Requires IP restrictions: write. Use the entry id from the list endpoint.
curl -X DELETE https://my.dashboardfox.app/api/v1/workspaces/87/ip-restrictions/entries/5 \ -H "Authorization: Bearer $DFX_KEY"
{"deleted": true, "ip_cidr": "203.0.113.7", "sync_queued": true}
While restrictions are on, the last entry cannot be removed (409 last_ip_protected). Turn restrictions off first.
Turn restrictions on or off: PUT /workspaces/{id}/ip-restrictions/settings
Requires IP restrictions: admin.
curl -X PUT https://my.dashboardfox.app/api/v1/workspaces/87/ip-restrictions/settings \ -H "Authorization: Bearer $DFX_KEY" -H "Content-Type: application/json" \ -d '{"enabled": true}'
{"enabled": true, "changed": true}
Restrictions cannot be turned on while the allowlist is empty (409 no_entries).
Note: When restrictions are on, only addresses on the allowlist can reach the workspace. Make sure your own address is on the list before turning them on.
IP address rules
The ip_cidr field accepts:
Value | Example | Meaning |
|---|---|---|
A single IPv4 or IPv6 address |
| That address only |
A range (CIDR) |
| Every address in the range |
|
| The address your request comes from, as shown by |
|
| The range around the address your request comes from |
To keep the allowlist safe, the API refuses:
ranges wider than
/24for IPv4 or/56for IPv6private, reserved and special-purpose addresses, such as
10.0.0.0/8,192.168.0.0/16and127.0.0.1
Wider or private ranges can still be added on the IP Restrictions page in the portal.
Addresses are stored in a standard form: 203.0.113.7/32 is saved as 203.0.113.7, and IPv6 addresses are shortened and lower-cased.
Note: The addresses in this article (203.0.113.x, 198.51.100.x and 2001:db8::) are reserved for documentation, and the API refuses them. Use your own addresses.
Error codes
Status | Code | Meaning |
|---|---|---|
400 |
| The request body is not valid JSON |
400 |
|
|
400 |
| The label contains characters that are not allowed |
400 |
| A required field is missing or has the wrong type |
401 |
| No |
401 |
| The key is wrong, expired or revoked, or its creator is no longer an Agency Owner |
403 |
| The key does not have the permission this endpoint needs |
403 |
| The key is restricted to other IP addresses |
404 |
| The workspace does not exist or this key cannot use it |
404 |
| No entry with this ID in the workspace |
409 |
| The address is already on the allowlist |
409 |
| More than one entry has this label; rename or remove the duplicates in the portal |
409 |
| The last entry cannot be removed while restrictions are on |
409 |
| Restrictions cannot be turned on with an empty allowlist |
413 |
| The request body is over 10 KB |
422 |
| The address or range is too broad or not a public address |
429 |
| Too many requests; wait a minute and retry |
429 |
| 20 changes in the last hour for this workspace; try again later |
Example: keeping a changing office IP on the allowlist
Many internet connections get a new public IP address from time to time. Without automation, the office is locked out of the workspace until someone updates the allowlist by hand. The set-by-label endpoint with auto keeps it current.
Create a key with Preset: IP updater (IP restrictions: write) for the one workspace.
On an always-on computer at the office, schedule this command to run every 5 minutes:
curl -4 -sS -X PUT https://my.dashboardfox.app/api/v1/workspaces/87/ip-restrictions/entries/by-label/office-ipv4 \ -H "Authorization: Bearer $DFX_KEY" -H "Content-Type: application/json" \ -d '{"ip_cidr": "auto"}'
The command must run on the office network, because auto uses the address the request comes from. Most runs return "changed": false and do nothing. When the office IP changes, the next run updates the entry, and the new address is allowed within about a minute. curl is built into macOS, Linux and Windows 10 and 11. Use cron, Task Scheduler or any scheduler you prefer.
Tip: If the office also uses IPv6, add a second entry with
curl -6, labeloffice-ipv6and{"ip_cidr": "auto/64"}. Each device changes its own IPv6 address regularly, so allowing the office's/64range keeps every device covered.