> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Whitelist Domains

> Retrieve or update the account-wide list of domains allowed to embed your dashboards (GET to list, PUT to update).

Manage the domains that are allowed to load embedded dashboards and metrics. Use **GET** to retrieve the current list and **PUT** to update it.

<Note>
  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](/developer-docs/security#domain-whitelisting) for more context.
</Note>

<Warning>
  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.
</Warning>

## Endpoints

<Tabs>
  <Tab title="GET – List whitelist domains">
    ```
    GET https://api.usedatabrain.com/api/v2/data-app/whitelist-domains
    ```

    Returns the account-wide list of whitelisted domains (shared by all Data Apps).
  </Tab>

  <Tab title="PUT – Update whitelist domains">
    ```
    PUT https://api.usedatabrain.com/api/v2/data-app/whitelist-domains
    Content-Type: application/json

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

    Replaces the account-wide whitelist with the given array of domains. Supports domain names, wildcards (e.g. `*.example.com`), IPs with optional port, and `localhost` with optional port.
  </Tab>
</Tabs>

## Authentication

All requests must include your **data app API key** in the `Authorization` header. See the [data app creation guide](/guides/datasources/create-a-data-app) and the [API Token guide](/developer-docs/helpers/api-token).

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your data app API key.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

<ParamField header="Content-Type" type="string">
  Required for PUT only. Must be `application/json`.
</ParamField>

## GET – Query parameters

None.

## PUT – Request Body

<ParamField body="domains" type="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.
</ParamField>

## Response

### GET response

<ResponseField name="data" type="string[]">
  Array of whitelisted domain strings. Empty array if none are set.
</ResponseField>

### PUT response

<ResponseField name="data" type="object">
  <ResponseField name="data.domains" type="string[]">
    The saved list of whitelisted domains.
  </ResponseField>
</ResponseField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/whitelist-domains' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

    ```bash cURL theme={"dark"}
    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"]}'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    // 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'] }),
    });
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    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"]},
    )
    ```
  </RequestExample>

  <ResponseExample>
    ```json GET – Success theme={"dark"}
    {
      "data": ["app.example.com", "*.customer.com", "localhost:3000"]
    }
    ```

    ```json PUT – Success theme={"dark"}
    {
      "data": {
        "domains": ["app.example.com", "*.customer.com"]
      }
    }
    ```

    ```json Error – Invalid body (PUT) theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Invalid domain format. Please enter domain/IP without http:// or https://"
      }
    }
    ```

    ```json Error – Invalid API key theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_API_KEY",
        "message": "invalid or expired API KEY, data app not found"
      }
    }
    ```
  </ResponseExample>
</Panel>

## Error codes

| Error Code                 | HTTP Status | Description                                                             |
| -------------------------- | ----------- | ----------------------------------------------------------------------- |
| `INVALID_DATA_APP_API_KEY` | 400         | Missing or invalid data app API key                                     |
| `INVALID_SERVICE_TOKEN`    | 400         | Invalid or expired token; cannot resolve company context                |
| `INVALID_REQUEST_BODY`     | 400         | Invalid or malformed `domains` (e.g. protocol included, invalid format) |
| `INTERNAL_SERVER_ERROR`    | 500         | Unexpected server error                                                 |

## Related

<CardGroup cols={2}>
  <Card title="Domain Whitelisting" href="/developer-docs/security#domain-whitelisting">
    Security and whitelist behavior
  </Card>

  <Card title="SMTP Settings" href="/developer-docs/helpers/api-reference/smtp-settings">
    Configure email (e.g. scheduled reports)
  </Card>
</CardGroup>