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

# Guest Token

> Generate secure guest tokens for embedding DataBrain dashboards and metrics in your application.

<Note>
  Guest tokens are designed for frontend embedding. Never expose your API key in frontend code - always generate tokens from your backend.
</Note>

<Note>
  **Simple Usage:** Only `clientId` and `dataAppName` are required. All other parameters (`params`, `permissions`, `expiryTime`, `datasourceName`, `datamartName`) are optional for advanced use cases.
</Note>

<Warning>
  The request body is validated strictly — any field not documented on this page is rejected with `INVALID_REQUEST_BODY`. In particular, `dataAppId`, `client_id`, `tenant_id`, and `permissions.dashboards` are **not** valid fields.
</Warning>

<Note>
  Guest tokens are free. There is no charge, metering, or purchase involved in generating them.
</Note>

<Info>
  **Advanced Features Available:**

  * Dashboard & metric-level filtering (`dashboardAppFilters`, `appFilters`)
  * Embed allowlisting (`params.allowedEmbeds`)
  * Fine-grained permissions control (`permissions` object)
  * Private metrics for end users (`userIdentifier`)
  * Timezone-aware queries (`params.timezone`)
  * Multi-datasource support (`datasourceName`)
  * Multi-datamart support (`datamartName`)
  * Conditional filter visibility (`hideDashboardFilters`, `isShowOnUrl`)
  * Token expiration management (`expiryTime`)
</Info>

## Authentication

All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our [data app creation guide](/guides/datasources/create-a-data-app) for details.

**Finding your API token:** For detailed instructions, see the [API Token guide](/developer-docs/helpers/api-token).

<Panel>
  <RequestExample>
    ```bash Authentication icon="fa-solid fa-terminal" theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/guest-token/create \
      --header 'Authorization: Bearer dbn_live_...' \
      --header 'Content-Type: application/json'
    ```
  </RequestExample>
</Panel>

#### Cloud Databrain Endpoint:

```http theme={"dark"}
POST https://api.usedatabrain.com/api/v2/guest-token/create
```

#### Self-hosted Databrain Endpoint:

```http theme={"dark"}
POST <SELF_HOSTED_URL>/api/v2/guest-token/create
```

## Headers

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

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

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json` for all requests.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="clientId" type="string" required>
  Unique identifier for the end user. This should be your user's ID from your system. Used for row-level security and access control.

  <Note>
    Use `"None"` as the value if no tenancy is configured for your workspace (e.g. `"clientId": "None"`).
  </Note>

  <Expandable title="Best practices">
    * Use your internal user ID
    * Keep it consistent across sessions
    * Alphanumeric characters recommended
  </Expandable>
</ParamField>

<ParamField body="dataAppName" type="string" required>
  The name of your data application. Must match an existing data app in your workspace and be alphanumeric.

  <Expandable title="Example values">
    * `"sales-dashboard"`
    * `"marketing-metrics"`
    * `"customer-analytics"`
  </Expandable>
</ParamField>

<ParamField body="params" type="object">
  Additional parameters for token customization and filtering.

  <ParamField body="params.allowedEmbeds" type="array">
    Optional allowlist of IDs this token can load.

    * Each entry must match the ID you pass to the embed component's `dashboardId` attribute — embed IDs and dashboard IDs both resolve.
    * If you provide `allowedEmbeds`, loading any ID not in the list fails with `UNAUTHORIZED`.
    * If this is omitted, there is no restriction on which embeds can be loaded by the token.
    * This is useful to restrict or enforce which dashboards or embedded analytics a guest can view, adding an extra layer of access control.

    <Expandable title="Example usage">
      ```json theme={"dark"}
      {
        "clientId": "user-456",
        "dataAppName": "sales-dashboard",
        "params": {
          "allowedEmbeds": ["<embed-or-dashboard-id-1>", "<embed-or-dashboard-id-2>"]
        }
      }
      ```
    </Expandable>
  </ParamField>

  <ParamField body="params.rlsSettings" type="array">
    Row-level security rules per metric. Each entry is `{ "metricId": string, "values": object }`, where `values` maps RLS variable names to the values enforced for this token. Unlike dashboard filters, RLS values are enforced server-side and cannot be changed by the end user.

    <Expandable title="Example usage">
      ```json theme={"dark"}
      {
        "clientId": "user-456",
        "dataAppName": "sales-dashboard",
        "params": {
          "rlsSettings": [
            { "metricId": "metric_123", "values": { "customer_id": "456", "region": "north-america" } }
          ]
        }
      }
      ```
    </Expandable>
  </ParamField>

  <ParamField body="params.accessPermissions" type="object">
    End-user dashboard-filter controls: `isAllowEndUserDashboardFilter` (boolean) and `dashboardFilterColumns` (array of `{ "tableName": string, "columns": string[] }`).
  </ParamField>

  <ParamField body="params.appFilters" type="array">
    Application-level filters for controlling access to individual metrics. Unlike RLS settings, app filters restrict access without requiring end user input.

    <Accordion title="Metric App Filter">
      <Tip>
        App filters are ideal for implementing metric-level access control that is invisible to end users.
      </Tip>

      <ParamField body="params.appFilters.metricId" type="string">
        The metric ID to apply filters to. Required if appFilters is provided.
      </ParamField>

      <ParamField body="params.appFilters.values" type="object">
        Filter values to apply to the metric. Supports multiple data types:

        <Info>
          Keys in `values` can use either the filter `label` or internal filter `name` (case-insensitive).
        </Info>

        * **Boolean**: `"paid_orders": true`
        * **Number**: `"amount": 500`
        * **String**: `"country": "USA"`
        * **Array** (multi-select): `"countries": ["USA", "CANADA"]`
        * **Date preset shortcut**: `"order_date": "Last 30 days"`
        * **SQL Query**: `{ "sql": "SELECT...", "columnName": "name" }`

        <Expandable title="Example with multiple filter types">
          ```json theme={"dark"}
          {
            "metricId": "metric_123",
            "values": {
              "paid_orders": true,
              "amount": 500,
              "country": ["USA", "CANADA"],
              "region": {
                "sql": "SELECT \"name\" FROM \"public\".\"regions\" WHERE isActive=true",
                "columnName": "name"
              }
            }
          }
          ```
        </Expandable>
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField body="params.dashboardAppFilters" type="array">
    Dashboard-level filters that apply to all metrics on a dashboard. Supports multiple filter types for flexible data filtering.

    <Accordion title="Dashboard AppFilters">
      <ParamField body="params.dashboardAppFilters.dashboardId" type="string">
        The dashboard ID to apply filters to. Required if dashboardAppFilters is provided.
      </ParamField>

      <ParamField body="params.dashboardAppFilters.values" type="object">
        Filter values to apply to the dashboard. Supports various filter formats:

        <Info>
          Keys in `values` can use either the dashboard filter `label` or internal filter `name` (case-insensitive).
        </Info>

        * **Single string**: `"name": "Eric"`
        * **Multi-select**: `"country": ["USA", "CANADA"]`
        * **Date range**: `"timePeriod": { "startDate": "2024-01-01", "endDate": "2024-03-23" }`
        * **Date preset shortcut**: `"timePeriod": "Last 30 days"`
        * **Number range**: `"price": { "min": 1000, "max": 5000 }`
        * **SQL query**: `{ "sql": "SELECT...", "columnName": "name" }`

        <Expandable title="Complete example with all filter types">
          ```json theme={"dark"}
          {
            "dashboardId": "dashboard_abc123",
            "values": {
              "name": "Eric",
              "country": ["USA", "CANADA"],
              "timePeriod": { 
                "startDate": "2024-01-01", 
                "endDate": "2024-03-23" 
              },
              "price": { "min": 1000, "max": 5000 },
              "region": {
                "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE isEnabled=true",
                "columnName": "name"
              }
            },
            "isShowOnUrl": false
          }
          ```
        </Expandable>
      </ParamField>

      <ParamField body="params.dashboardAppFilters.isShowOnUrl" default="true" type="boolean">
        Controls visibility of filter values in URL search parameters. When `false`, filters are applied but not visible to end users in the URL.

        <Tip>
          Set to `false` to hide sensitive filter criteria from end users while still applying the filtering logic.
        </Tip>
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField body="params.hideDashboardFilters" type="array">
    Array of filter names to hide from the dashboard interface. Use this to conditionally hide specific filters based on user permissions or context.

    <Expandable title="Example usage">
      ```json theme={"dark"}
      {
        "clientId": "user-456",
        "dataAppName": "sales-dashboard",
        "params": {
          "hideDashboardFilters": ["region_filter", "date_range", "status"]
        }
      }
      ```
    </Expandable>
  </ParamField>

  <ParamField body="params.accessPermissions" type="object">
    Optional advanced access controls for end-user dashboard filtering.

    <ParamField body="params.accessPermissions.isAllowEndUserDashboardFilter" type="boolean">
      Enables or disables end-user dashboard filter controls in embedded mode.
    </ParamField>

    <ParamField body="params.accessPermissions.dashboardFilterColumns" type="array">
      Optional allowlist for dashboard filterable columns. Each item must include `tableName` and `columns`.
    </ParamField>

    <ParamField body="params.accessPermissions.dashboardFilterColumns[].tableName" type="string" required>
      Fully qualified table name used in dashboard filters.
    </ParamField>

    <ParamField body="params.accessPermissions.dashboardFilterColumns[].columns" type="array[string]" required>
      Column names allowed for dashboard filter evaluation for the specified table.
    </ParamField>
  </ParamField>

  <ParamField body="params.userIdentifier" type="string">
    Unique identifier for the end user in your system. Enables features like creating **private metrics** and **publishing metrics** directly from the embed view.

    <Warning>
      The `isAllowPrivateMetricsByDefault` setting must be enabled when creating the dashboard for this feature to work.
    </Warning>

    <Expandable title="Use case example">
      When set, metrics created by this user identifier can be:

      * Saved as private (visible only to this user)
      * Published to share with other users
      * Managed independently per user

      ```json theme={"dark"}
      {
        "clientId": "client-123",
        "dataAppName": "analytics-app",
        "params": {
          "userIdentifier": "user_john_doe_789"
        }
      }
      ```
    </Expandable>
  </ParamField>

  <ParamField body="params.timezone" type="string">
    IANA timezone string for timezone-aware queries and date/time formatting. When provided, SQL queries will be executed with this timezone setting, ensuring consistent date/time handling across different timezones.

    <Info>
      The timezone is used to set the database session timezone for SQL queries, ensuring that date/time operations are performed in the specified timezone.
    </Info>

    <Info>
      **Supported Datasources:**

      * Clickhouse
      * Trino
      * Redshift
      * CockroachDB
      * Postgres
      * MSSQL
    </Info>

    <Tip>
      Want to implement timezone-aware dashboards end to end? See the full step-by-step guide: [Timezone Handling in Guest Token](/developer-docs/solutions-alchemy/guest-token-timezone).
    </Tip>

    <Expandable title="Common timezone values">
      * `"UTC"` - Coordinated Universal Time
      * `"America/New_York"` - Eastern Time (US)
      * `"America/Los_Angeles"` - Pacific Time (US)
      * `"Europe/London"` - Greenwich Mean Time / British Summer Time
      * `"Asia/Kolkata"` - Indian Standard Time
      * `"Australia/Sydney"` - Australian Eastern Time

      ```json theme={"dark"}
      {
        "clientId": "user-456",
        "dataAppName": "sales-dashboard",
        "params": {
          "timezone": "America/New_York"
        }
      }
      ```
    </Expandable>
  </ParamField>
</ParamField>

<ParamField body="permissions" type="object">
  Permission settings for the embedded interface.

  <Accordion title="Permission Options">
    <ParamField body="permissions.isEnableArchiveMetrics" type="boolean">
      Allow archiving metrics.
    </ParamField>

    <ParamField body="permissions.isEnableManageMetrics" type="boolean">
      Allow managing metrics (view, edit, organize).
    </ParamField>

    <ParamField body="permissions.isEnableCreateDashboardView" type="boolean">
      Allow creating custom dashboard views.
    </ParamField>

    <ParamField body="permissions.isEnableMetricUpdation" type="boolean">
      Allow updating metric configurations.
    </ParamField>

    <ParamField body="permissions.isEnableCustomizeLayout" type="boolean">
      Allow customizing dashboard layout.
    </ParamField>

    <ParamField body="permissions.isEnableUnderlyingData" type="boolean">
      Allow viewing underlying data behind charts.
    </ParamField>

    <ParamField body="permissions.isEnableDownloadMetrics" type="boolean">
      Allow downloading metric data.
    </ParamField>

    <ParamField body="permissions.isShowSideBar" type="boolean">
      Show the sidebar navigation.
    </ParamField>

    <ParamField body="permissions.isShowDashboardName" type="boolean">
      Show the dashboard name in the interface.
    </ParamField>

    <ParamField body="permissions.isDisableMetricCreation" type="boolean">
      Disable metric creation in embedded dashboards. When set to `true`, end users cannot create new metrics.

      <Expandable title="Use case">
        * Setting this to `true` disables only the metric creation feature for end users in the embedded interface.
        * If you want to allow metric creation again, mint a new token with this option set to `false` or removed, and check the Data App's Access Control settings and the <a href="/developer-docs/helpers/component-options-reference">component options</a> (`options.disableMetricCreation`).
        * Overrides other metric creation permissions when enabled.
      </Expandable>
    </ParamField>
  </Accordion>
</ParamField>

<ParamField body="expiryTime" type="number">
  **Optional.** Token expiration time in milliseconds from now. If not provided, token never expires.

  <Expandable title="Common values">
    * `3600000` - 1 hour (3600 \* 1000 ms)
    * `86400000` - 24 hours
    * `604800000` - 7 days
  </Expandable>
</ParamField>

<ParamField body="datamartName" type="string">
  **Optional.** Scope the token to a specific Datamart.
</ParamField>

<ParamField body="datasourceName" type="string">
  **Optional.** Datasource name for multi-datasource connection setups. Required when your data app uses multiple datasources.

  <Info>
    The datasource name is available in the **Data Studio** tab of your dashboard. This parameter is only necessary if you have configured multiple datasources for your data app.
  </Info>

  <Expandable title="Multi-datasource example">
    ```json theme={"dark"}
    {
      "clientId": "user-456",
      "dataAppName": "analytics-app",
      "datasourceName": "production_db_replica"
    }
    ```
  </Expandable>
</ParamField>

<ParamField body="datamartName" type="string">
  **Optional.** Datamart name for multi-datamart connection setups. Use this when your data app can resolve multiple datamarts and you want to pin token execution to one datamart.

  <Info>
    If both `datasourceName` and `datamartName` are omitted, Databrain resolves defaults from the data app context.
  </Info>

  <Expandable title="Multi-datamart example">
    ```json theme={"dark"}
    {
      "clientId": "user-456",
      "dataAppName": "analytics-app",
      "datamartName": "sales-datamart"
    }
    ```
  </Expandable>
</ParamField>

<Panel>
  <RequestExample>
    ```bash cURL (Simple) icon="fa-solid fa-terminal" theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/guest-token/create \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "clientId": "user-456",
        "dataAppName": "sales-dashboard"
      }'
    ```

    ```bash cURL (Advanced) icon="fa-solid fa-terminal" theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/guest-token/create \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "clientId": "user-456",
        "dataAppName": "sales-dashboard",
        "params": {
          "rlsSettings": [
            {
              "metricId": "metric_123",
              "values": {
                "customer_id": "456",
                "region": "north-america"
              }
            }
          ]
        },
        "expiryTime": 3600000
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/guest-token/create', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        clientId: 'user-456',
        dataAppName: 'sales-dashboard',
        params: {
          rlsSettings: [
            {
              metricId: 'metric_123',
              values: {
                customer_id: '456',
                region: 'north-america'
              }
            }
          ]
        },
        expiryTime: 3600000
      })
    });
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    response = requests.post(
        'https://api.usedatabrain.com/api/v2/guest-token/create',
        headers={
            'Authorization': 'Bearer dbn_live_abc123...',
            'Content-Type': 'application/json'
        },
        json={
            'clientId': 'user-456',
            'dataAppName': 'sales-dashboard',
            'params': {
                'rlsSettings': [
                    {
                        'metricId': 'metric_123',
                        'values': {
                            'customer_id': '456',
                            'region': 'north-america'
                        }
                    }
                ]
            },
            'expiryTime': 3600000
        }
    )
    ```

    ```java Java icon="fa-brands fa-java" theme={"dark"}
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.net.URI;
    import com.fasterxml.jackson.databind.ObjectMapper;
    import java.util.Map;
    import java.util.List;

    HttpClient client = HttpClient.newHttpClient();
    ObjectMapper mapper = new ObjectMapper();

    Map<String, Object> requestBody = Map.of(
        "clientId", "user-456",
        "dataAppName", "sales-dashboard",
        "params", Map.of(
            "rlsSettings", List.of(
                Map.of(
                    "metricId", "metric_123",
                    "values", Map.of(
                        "customer_id", "456",
                        "region", "north-america"
                    )
                )
            )
        ),
        "expiryTime", 3600000
    );

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.usedatabrain.com/api/v2/guest-token/create"))
        .header("Authorization", "Bearer dbn_live_abc123...")
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(requestBody)))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    ```

    ```php PHP icon="fa-brands fa-php" theme={"dark"}
    <?php
    $curl = curl_init();

    $data = [
        'clientId' => 'user-456',
        'dataAppName' => 'sales-dashboard',
        'params' => [
            'rlsSettings' => [
                [
                    'metricId' => 'metric_123',
                    'values' => [
                        'customer_id' => '456',
                        'region' => 'north-america'
                    ]
                ]
            ]
        ],
        'expiryTime' => 3600000
    ];

    curl_setopt_array($curl, [
        CURLOPT_URL => 'https://api.usedatabrain.com/api/v2/guest-token/create',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => json_encode($data),
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer dbn_live_abc123...',
            'Content-Type: application/json'
        ],
    ]);

    $response = curl_exec($curl);
    curl_close($curl);
    ?>
    ```

    ```ruby Ruby icon="fa-solid fa-gem" theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/guest-token/create')
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(uri)
    request['Authorization'] = 'Bearer dbn_live_abc123...'
    request['Content-Type'] = 'application/json'

    request.body = {
      clientId: 'user-456',
      dataAppName: 'sales-dashboard',
      params: {
        rlsSettings: [
          {
            metricId: 'metric_123',
            values: {
              customer_id: '456',
              region: 'north-america'
            }
          }
        ]
      },
      expiryTime: 3600000
    }.to_json

    response = http.request(request)
    ```

    ```go Go icon="fa-brands fa-golang" theme={"dark"}
    package main

    import (
        "bytes"
        "encoding/json"
        "net/http"
    )

    type RLSValue struct {
        CustomerID string `json:"customer_id"`
        Region     string `json:"region"`
    }

    type RLSSetting struct {
        MetricID string   `json:"metricId"`
        Values   RLSValue `json:"values"`
    }

    type Params struct {
        RLSSettings []RLSSetting `json:"rlsSettings"`
    }

    type RequestBody struct {
        ClientID     string `json:"clientId"`
        DataAppName  string `json:"dataAppName"`
        Params       Params `json:"params"`
        ExpiryTime   int    `json:"expiryTime"`
    }

    func main() {
        requestBody := RequestBody{
            ClientID:    "user-456",
            DataAppName: "sales-dashboard",
            Params: Params{
                RLSSettings: []RLSSetting{
                    {
                        MetricID: "metric_123",
                        Values: RLSValue{
                            CustomerID: "456",
                            Region:     "north-america",
                        },
                    },
                },
            },
            ExpiryTime:   3600000,
        }

        jsonData, _ := json.Marshal(requestBody)
        
        req, _ := http.NewRequest("POST", "https://api.usedatabrain.com/api/v2/guest-token/create", bytes.NewBuffer(jsonData))
        req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, _ := client.Do(req)
        defer resp.Body.Close()
    }
    ```

    ```csharp C# icon="fa-solid fa-code" theme={"dark"}
    using System;
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json;

    public class GuestTokenRequest
    {
        [JsonProperty("clientId")]
        public string ClientId { get; set; }
        
        [JsonProperty("dataAppName")]
        public string DataAppName { get; set; }
        
        [JsonProperty("params")]
        public Params Params { get; set; }
        
        [JsonProperty("expiryTime")]
        public int ExpiryTime { get; set; }
    }

    public class Params
    {
        [JsonProperty("rlsSettings")]
        public RLSSetting[] RlsSettings { get; set; }
    }

    public class RLSSetting
    {
        [JsonProperty("metricId")]
        public string MetricId { get; set; }
        
        [JsonProperty("values")]
        public Values Values { get; set; }
    }

    public class Values
    {
        [JsonProperty("customer_id")]
        public string CustomerId { get; set; }
        
        [JsonProperty("region")]
        public string Region { get; set; }
    }

    var client = new HttpClient();
    var request = new GuestTokenRequest
    {
        ClientId = "user-456",
        DataAppName = "sales-dashboard",
        Params = new Params
        {
            RlsSettings = new[]
            {
                new RLSSetting
                {
                    MetricId = "metric_123",
                    Values = new Values
                    {
                        CustomerId = "456",
                        Region = "north-america"
                    }
                }
            }
        },
        ExpiryTime = 3600000
    };

    var json = JsonConvert.SerializeObject(request);
    var content = new StringContent(json, Encoding.UTF8, "application/json");

    client.DefaultRequestHeaders.Add("Authorization", "Bearer dbn_live_abc123...");
    var response = await client.PostAsync("https://api.usedatabrain.com/api/v2/guest-token/create", content);
    ```

    ```bash cURL (Dashboard Filters) icon="fa-solid fa-terminal" theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/guest-token/create \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "clientId": "user-789",
        "dataAppName": "regional-analytics",
        "params": {
          "dashboardAppFilters": [
            {
              "dashboardId": "dashboard_abc123",
              "values": {
                "region": ["north-america", "europe"],
                "timePeriod": {
                  "startDate": "2024-01-01",
                  "endDate": "2024-12-31"
                },
                "revenue": {
                  "min": 10000,
                  "max": 500000
                }
              },
              "isShowOnUrl": false
            }
          ]
        },
        "expiryTime": 7200000
      }'
    ```

    ```bash cURL (Permissions + Private Metrics) icon="fa-solid fa-terminal" theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/guest-token/create \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "clientId": "tenant-456",
        "dataAppName": "self-service-analytics",
        "params": {
          "userIdentifier": "analyst_john_123",
          "timezone": "America/New_York",
          "appFilters": [
            {
              "metricId": "metric_abc",
              "values": {
                "paid_orders": true,
                "amount": 1000,
                "countries": ["USA", "CANADA"]
              }
            }
          ],
          "hideDashboardFilters": ["internal_cost", "profit_margin"]
        },
        "permissions": {
          "isEnableArchiveMetrics": true,
          "isEnableManageMetrics": true,
          "isEnableMetricUpdation": true,
          "isEnableCustomizeLayout": true,
          "isEnableUnderlyingData": false,
          "isEnableDownloadMetrics": true,
          "isDisableMetricCreation": false
        }
      }'
    ```

    ```bash cURL (Multi-Datasource) icon="fa-solid fa-terminal" theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/guest-token/create \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "clientId": "production-client",
        "dataAppName": "enterprise-bi",
        "datasourceName": "production_replica_west",
        "params": {
          "dashboardAppFilters": [
            {
              "dashboardId": "ops_dashboard",
              "values": {
                "environment": "production"
              }
            }
          ]
        },
        "expiryTime": 3600000
      }'
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 - Success theme={"dark"}
    {
      "token": "3affda8b-7bd4-4a88-9687-105a94cfffab"
    }
    ```

    ```json 400 - Bad Request theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_NAME",
        "message": "invalid data app name, data app name not found",
        "status": 400
      }
    }
    ```

    ```json 401 - Unauthorized theme={"dark"}
    {
      "error": {
        "code": "INVALID_API_KEY", 
        "message": "Invalid or missing API key",
        "status": 401
      }
    }
    ```
  </ResponseExample>
</Panel>

## Response

<ResponseField name="token" type="string">
  UUID token for authentication. Pass this to your frontend component for embedding.
</ResponseField>

<ResponseField name="error" type="null | object">
  Error object if the request failed, otherwise `null` for successful requests.
</ResponseField>

## HTTP Status Code Summary

| Status Code | Description                                       |
| ----------- | ------------------------------------------------- |
| `200`       | **OK** - Request succeeded                        |
| `400`       | **Bad Request** - Invalid request parameters      |
| `401`       | **Unauthorized** - Invalid or missing API key     |
| `403`       | **Forbidden** - Access denied to resource         |
| `404`       | **Not Found** - Resource not found                |
| `429`       | **Too Many Requests** - Rate limit exceeded       |
| `500`       | **Internal Server Error** - Server error occurred |

## Error Codes

| Error Code                 | HTTP Status | Description                                                                |
| -------------------------- | ----------- | -------------------------------------------------------------------------- |
| `AUTHENTICATION_ERROR`     | 401         | Invalid or missing API key                                                 |
| `INVALID_REQUEST_BODY`     | 400         | Missing, invalid, or unknown parameters (unrecognized fields are rejected) |
| `CLIENT_ID_ERROR`          | 400         | Invalid clientId format or value                                           |
| `INVALID_DATA_APP_NAME`    | 400         | `dataAppName` doesn't match any Data App (case-sensitive)                  |
| `WORKSPACE_ID_ERROR`       | 404         | Workspace not found or inaccessible                                        |
| `DASHBOARD_PARAM_ERROR`    | 400         | Invalid dashboard filter parameters                                        |
| `APP_FILTER_PARAM_ERROR`   | 400         | Invalid app filter configuration                                           |
| `RLS_SETTINGS_PARAM_ERROR` | 400         | Invalid RLS settings                                                       |
| `DATASOURCE_NAME_ERROR`    | 400         | `datasourceName` doesn't resolve                                           |
| `DATAMART_NAME_ERROR`      | 400         | `datamartName` doesn't resolve                                             |
| `INTERNAL_SERVER_ERROR`    | 500         | Server error                                                               |

These are the mint-time errors from this endpoint. At embed runtime (after minting), the distinct errors are `INVALID_TOKEN` (token not found in this deployment), `TOKEN_EXPIRED`, `UNAUTHORIZED_ORIGIN`, `UNAUTHORIZED`, and `INVALID_ID` — see the [Error Codes Reference](/developer-docs/reference/error-codes). Rate limiting surfaces as HTTP `429` with a `Retry-After` header (see [Rate Limiting](/developer-docs/rate-limiting)).

## Quick Start Guide

<Card title="Getting Started" icon="sparkles" href="https://docs.usedatabrain.com/developer-docs" />

<Warning>
  **Rate Limiting**: API requests are limited to prevent abuse. Implement exponential backoff for rate limited requests (429 status).
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Embed a Pre-built Dashboard/Metric" icon="code" href="/developer-docs/helpers/api-reference/create-embed">
    Create embed configurations for your data apps
  </Card>

  <Card title="Create Data App" icon="database" href="/guides/datasources/create-a-data-app">
    Create data apps and get your API tokens
  </Card>

  <Card title="How to Embed" icon="chart-line" href="/developer-docs/how-to-embed">
    Learn how to embed dashboards in your app
  </Card>

  <Card title="API Token Helper" icon="key" href="/developer-docs/helpers/api-token">
    Learn more about API token management
  </Card>
</CardGroup>