> ## 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`)
  * Per-dashboard metric visibility (`params.hideDashboardMetrics`)
  * 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- and metric-filter controls. Supported fields include the filter permissions, optional column allowlists, and filter-name rename permissions.
  </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.hideDashboardMetrics" type="array">
    Metrics to hide from specific embedded dashboards. Each item targets one dashboard and removes the selected metrics and their layout cards from that dashboard's embed response.

    <ParamField body="params.hideDashboardMetrics[].dashboardId" type="string" required>
      External ID of the dashboard on which to hide the metrics. The dashboard must belong to the data app and workspace scope associated with the API token.
    </ParamField>

    <ParamField body="params.hideDashboardMetrics[].metricIds" type="array[string]" required>
      Public metric IDs to hide on the specified dashboard. Every metric must be present on that dashboard.
    </ParamField>

    <Expandable title="Example usage">
      ```json theme={"dark"}
      {
        "clientId": "user-456",
        "dataAppName": "sales-dashboard",
        "params": {
          "hideDashboardMetrics": [
            {
              "dashboardId": "sales-overview",
              "metricIds": ["revenue-by-region", "gross-margin"]
            }
          ]
        }
      }
      ```
    </Expandable>

    <Note>
      This setting controls dashboard presentation for this guest token. It does not delete, archive, or change the metrics globally. Configurations for other dashboard IDs do not affect the current dashboard. If the same dashboard appears more than once, the backend combines the metric IDs from all matching entries.
    </Note>
  </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 body="params.accessPermissions.isAllowEndUserMetricFilter" type="boolean">
      Enables or disables end-user metric filter interactions in embedded mode.
    </ParamField>

    <ParamField body="params.accessPermissions.metricFilterColumns" type="array">
      Optional allowlist for columns that end users can use in metric filters. Each item must include `tableName` and `columns`.
    </ParamField>

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

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

    <ParamField body="params.accessPermissions.isAllowDashboardFilterNameChange" type="boolean">
      Enables or disables end-user renaming of dashboard filter labels in embedded mode.
    </ParamField>

    <ParamField body="params.accessPermissions.isAllowMetricFilterNameChange" type="boolean">
      Enables or disables end-user renaming of metric filter labels in embedded mode.
    </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 or a `hideDashboardMetrics` dashboard outside the API token's data app/workspace scope |
| `INVALID_METRIC_ID`        | 400         | A `hideDashboardMetrics.metricIds` value is not present on the specified dashboard                                         |
| `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>