Skip to main content
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/whitelist-domains' \
  --header 'Authorization: Bearer dbn_live_abc123...'

curl --request PUT \
  --url 'https://api.usedatabrain.com/api/v2/data-app/whitelist-domains' \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{"domains": ["app.example.com", "*.customer.com", "localhost:3000"]}'

// List
const listRes = await fetch('https://api.usedatabrain.com/api/v2/data-app/whitelist-domains', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer dbn_live_abc123...' }
});
const { data: domains } = await listRes.json();

// Update
await fetch('https://api.usedatabrain.com/api/v2/data-app/whitelist-domains', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ domains: ['app.example.com', '*.customer.com'] }),
});

import requests

headers = {"Authorization": "Bearer dbn_live_abc123..."}

# List
r = requests.get("https://api.usedatabrain.com/api/v2/data-app/whitelist-domains", headers=headers)
domains = r.json().get("data", [])

# Update
requests.put(
    "https://api.usedatabrain.com/api/v2/data-app/whitelist-domains",
    headers={**headers, "Content-Type": "application/json"},
    json={"domains": ["app.example.com", "*.customer.com"]},
)

{
  "data": ["app.example.com", "*.customer.com", "localhost:3000"]
}

{
  "data": {
    "domains": ["app.example.com", "*.customer.com"]
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "Invalid domain format. Please enter domain/IP without http:// or https://"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "invalid or expired API KEY, data app not found"
  }
}
GET
/
api
/
v2
/
data-app
/
whitelist-domains
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/whitelist-domains' \
  --header 'Authorization: Bearer dbn_live_abc123...'

curl --request PUT \
  --url 'https://api.usedatabrain.com/api/v2/data-app/whitelist-domains' \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{"domains": ["app.example.com", "*.customer.com", "localhost:3000"]}'

// List
const listRes = await fetch('https://api.usedatabrain.com/api/v2/data-app/whitelist-domains', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer dbn_live_abc123...' }
});
const { data: domains } = await listRes.json();

// Update
await fetch('https://api.usedatabrain.com/api/v2/data-app/whitelist-domains', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ domains: ['app.example.com', '*.customer.com'] }),
});

import requests

headers = {"Authorization": "Bearer dbn_live_abc123..."}

# List
r = requests.get("https://api.usedatabrain.com/api/v2/data-app/whitelist-domains", headers=headers)
domains = r.json().get("data", [])

# Update
requests.put(
    "https://api.usedatabrain.com/api/v2/data-app/whitelist-domains",
    headers={**headers, "Content-Type": "application/json"},
    json={"domains": ["app.example.com", "*.customer.com"]},
)

{
  "data": ["app.example.com", "*.customer.com", "localhost:3000"]
}

{
  "data": {
    "domains": ["app.example.com", "*.customer.com"]
  }
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "Invalid domain format. Please enter domain/IP without http:// or https://"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "invalid or expired API KEY, data app not found"
  }
}
Manage the domains that are allowed to load embedded dashboards and metrics. Use GET to retrieve the current list and PUT to update it.
Domain whitelisting is a security feature. Requests from non-whitelisted origins are rejected even with a valid API key or guest token. See Domain Whitelisting for more context.
The whitelist is stored account-wide: although this endpoint is authenticated with a Data App API key, it reads and writes the single list shared by all Data Apps in your account. A PUT replaces the whole account’s whitelist — include every domain used by every Data App, not just the one whose key you’re using.

​
Endpoints

GET https://api.usedatabrain.com/api/v2/data-app/whitelist-domains
Returns the account-wide list of whitelisted domains (shared by all Data Apps).

​
Authentication

All requests must include your data app API key in the Authorization header. See the data app creation guide and the API Token guide.

​
Headers

​
Authorization
string
required
Bearer token for API authentication. Use your data app API key.
Authorization: Bearer dbn_live_abc123...
​
Content-Type
string
Required for PUT only. Must be application/json.

​
GET – Query parameters

None.

​
PUT – Request Body

​
domains
array
required
Array of domain strings. Each entry must be one of:
  • A valid domain with at least two labels (e.g. app.example.com)
  • A wildcard subdomain (e.g. *.example.com)
  • An IPv4 address with optional port (e.g. 192.168.1.1 or 192.168.1.1:3000)
  • localhost with optional port (e.g. localhost or localhost:8080)
Do not include http:// or https://. Pass an empty array [] to clear all whitelisted domains.

​
Response

​
GET response

​
data
string[]
Array of whitelisted domain strings. Empty array if none are set.

​
PUT response

​
data
object
​
data.domains
string[]
The saved list of whitelisted domains.

​
Examples

​
Error codes

Error CodeHTTP StatusDescription
INVALID_DATA_APP_API_KEY400Missing or invalid data app API key
INVALID_SERVICE_TOKEN400Invalid or expired token; cannot resolve company context
INVALID_REQUEST_BODY400Invalid or malformed domains (e.g. protocol included, invalid format)
INTERNAL_SERVER_ERROR500Unexpected server error

Domain Whitelisting

Security and whitelist behavior

SMTP Settings

Configure email (e.g. scheduled reports)