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:

  1. 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.

  2. The API address for your region. A key only works in the region where it was created.

  3. 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

https://my.dashboardfox.app/api/v1

Europe

https://my-eu.dashboardfox.app/api/v1

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

429 rate_limited

Requests per client IP

120 per minute

429 rate_limited

Changes to one workspace's IP restrictions

20 per hour, all keys combined

429 change_limit_reached

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

/whoami

Any valid key

Describes the key and the IP address the server sees

GET

/workspaces

Workspaces: read

Lists the workspaces the key can access

GET

/workspaces/{id}/ip-restrictions

IP restrictions: read

Shows whether restrictions are on and lists allowlist entries

POST

/workspaces/{id}/ip-restrictions/entries

IP restrictions: write

Adds an allowlist entry

PUT

/workspaces/{id}/ip-restrictions/entries/by-label/{label}

IP restrictions: write

Creates or updates the entry with this label

DELETE

/workspaces/{id}/ip-restrictions/entries/{entryId}

IP restrictions: write

Removes an allowlist entry

PUT

/workspaces/{id}/ip-restrictions/settings

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

ip_cidr

Yes

An IP address, a range, or auto (see IP address rules)

label

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

ip_cidr

Yes

An IP address, a range, auto or auto/<prefix>

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

created

changed

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

203.0.113.7, 2001:db8::1

That address only

A range (CIDR)

198.51.100.0/24, 2001:db8:1:2::/64

Every address in the range

auto

auto

The address your request comes from, as shown by /whoami

auto/<prefix>

auto/64

The range around the address your request comes from

To keep the allowlist safe, the API refuses:

  • ranges wider than /24 for IPv4 or /56 for IPv6

  • private, reserved and special-purpose addresses, such as 10.0.0.0/8, 192.168.0.0/16 and 127.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

invalid_json

The request body is not valid JSON

400

invalid_ip

ip_cidr is missing or not a valid address or range

400

invalid_label

The label contains characters that are not allowed

400

invalid_body

A required field is missing or has the wrong type

401

missing_api_key

No Authorization header was sent

401

invalid_api_key

The key is wrong, expired or revoked, or its creator is no longer an Agency Owner

403

insufficient_scope

The key does not have the permission this endpoint needs

403

ip_not_allowed

The key is restricted to other IP addresses

404

workspace_not_found

The workspace does not exist or this key cannot use it

404

entry_not_found

No entry with this ID in the workspace

409

ip_exists

The address is already on the allowlist

409

label_ambiguous

More than one entry has this label; rename or remove the duplicates in the portal

409

last_ip_protected

The last entry cannot be removed while restrictions are on

409

no_entries

Restrictions cannot be turned on with an empty allowlist

413

payload_too_large

The request body is over 10 KB

422

ip_not_allowed

The address or range is too broad or not a public address

429

rate_limited

Too many requests; wait a minute and retry

429

change_limit_reached

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.

  1. Create a key with Preset: IP updater (IP restrictions: write) for the one workspace.

  2. 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, label office-ipv6 and {"ip_cidr": "auto/64"}. Each device changes its own IPv6 address regularly, so allowing the office's /64 range keeps every device covered.