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

# Token

To obtain a guest token from DataBrain, utilize our REST API from your backend system. Each request will generate a unique guest token, ensuring security and flexibility.

Once you acquire the guest token, you can seamlessly pass it to your frontend application, where it can be integrated with the <Link href="/guides/embed/web-component">web component</Link>.

<Info>`Create API key from Databrain's dashboard` that should be passed in the headers in these requests.</Info>

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

### Quick start (simple use case):

When you need a guest token that you want to use across dashboards and metrics, all you have to do is pass `clientId`, `dataAppName`. If `expiryTime` is not passed, the token will not expire.

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

Generating GUEST TOKEN for your Dashboard/Metric Component.

### Headers

| Name            | Type   | Description                                                                        |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| Authorization\* | String | Bearer [API TOKEN](https://docs.usedatabrain.com/developer-docs/helpers/api-token) |
| Content-Type\*  | String | Must be set to `application/json` for all requests                                 |

### Request Body

| Name           | Type   | Description                                                                                                                   |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| dataAppName\*  | String | Your Data App Name                                                                                                            |
| clientId\*     | String | Client ID for whom this guest token is generated. (`"clientId": "None"` if no tenancy selected)                               |
| params         | Object | Additional Params: `allowedEmbeds`, `dashboardAppFilters`, `appFilters`, `hideDashboardFilters`, `userIdentifier`, `timezone` |
| expiryTime     | Number | In milliseconds. Common values: `3600000` (1 hour), `86400000` (24 hours), `604800000` (7 days)                               |
| datasourceName | String | Datasource name from Data Studio (*important in case of multi-datasource embed setup*)                                        |

```json theme={"dark"}
// 200: OK
{
  "token": "..."
}
```

```json theme={"dark"}
// 400: Bad Request
{
  "error": {
    "message": "invalid dashboard id",
    "code": "<ERROR_CODE>"
  }
}
```

```json theme={"dark"}
// 401: Unauthorized
{
  "error": {
    "message": "API key is invalid or expired",
    "code": "AUTHENTICATION_ERR"
  }
}
```

### Request Body Examples:

#### Simple Request Body:

```json theme={"dark"}
{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname"
}
```

#### Request Body with App Level Metric Filter:

> **App filter**\
> A metric level filter designed specifically for controlling access to individual metrics. Unlike general RLS settings, it restricts access without requiring end user input or control.

```json theme={"dark"}
{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "appFilters": [{
      "metricId": "The id of the metric you want to have app filters",
      "values": {
        "paid_orders": true,
        "amount": 500,
        "country": ["USA", "CANADA"] || "USA", // based on filter variant (select or multi)
        {
          "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE isEnabled=true",
          "columnName": "name"
        }
      }
    }]
  }
}
```

<CardGroup cols={2}>
  <Card title="Request.json" href="/images/guides/Request.json" icon="file-arrow-down" horizontal />
</CardGroup>

### Dashboard App Filters:

#### Request Body with Dashboard filters:

```json theme={"dark"}
{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "dashboardAppFilters": [
      {
        "dashboardId": "dashboard-id",
        "values": {
          // single string
          "name": "Eric",

          // multi select
          "country": ["USA", "CANADA"] || "USA", // based on filter variant (select or multi)
          {
            "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE isEnabled=true",
            "columnName": "name"
          },

          // date-picker
          "timePeriod": { "startDate": "2024-01-01", "endDate": "2024-3-23" },

          // range
          "price": { "min": 1000, "max": 5000 }
        },
        "isShowOnUrl": true // true/false
      }
    ]
  }
}
```

In the above code snippet, `"name"`, `"country"`, `"timePeriod"`, and `"price"` are Dashboard App filters.\
When you disable the `isShowOnUrl`, the filter will not be visible to end users as search params on URL.

### Datasource \[Multi Datasource connection]:

```json theme={"dark"}
{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "datasourceName": "data source name"
}
```

`datasourceName` is available in app data studio tab.

### Hide Dashboard Filters:

To hide dashboard filters in an embedded dashboard:

```json theme={"dark"}
{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "hideDashboardFilters": ["filter 1", "filter 2"] // name of dashboard filters to hide
  }
}
```

### Allowed Embeds (optional)

To restrict where a guest token can be used, pass an allowlist of embed IDs in `params.allowedEmbeds`.
When set, the token will only be able to load embedded dashboards whose `dashboardId` is included in that list.

```json theme={"dark"}
{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "allowedEmbeds": ["embed_abc123", "embed_def456"]
  }
}
```

### Dashboard Permissions

To enable or disable few dashboard permissions from backend:

```json theme={"dark"}
{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "permissions": {
    "isEnableArchiveMetrics": true, // true or false
    "isEnableManageMetrics": true, // true or false
    "isEnableCreateDashboardView": true, // true or false - allow creating custom dashboard views
    "isEnableMetricUpdation": true, // true or false
    "isEnableCustomizeLayout": true, // true or false
    "isEnableUnderlyingData": true, // true or false
    "isEnableDownloadMetrics": true, // true or false
    "isShowSideBar": true, // true or false - show the sidebar navigation
    "isShowDashboardName": true, // true or false - show the dashboard name in the interface
    "isDisableMetricCreation": false // true or false - disable metric creation for end users
  }
}
```

### User Identifier for Private & Publish Metrics

Use `userIdentifier` inside the `params` object to uniquely identify the end-user in your embedded dashboard.\
This enables features such as creating **private metrics** and **publishing metrics** directly from the embed view.

```json theme={"dark"}
{
  "clientId": "id",
  "dataAppName": "dataappname",
  "params": {
    "userIdentifier": "unique-user-id-123"
  }
}

```

Note: userIdentifier should be a unique string representing the logged-in user in your system.

When set, any metrics created by this identifier can be managed (private or published) within the embedded environment.

`isAllowPrivateMetricsByDefault` should be enabled while creating the dashboard.

### Timezone

Use `timezone` inside the `params` object to specify an 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.

**Supported Datasources:** Clickhouse, Trino, Redshift, CockroachDB, Postgres, MSSQL

Common timezone values: `"UTC"`, `"America/New_York"`, `"America/Los_Angeles"`, `"Europe/London"`, `"Asia/Kolkata"`, `"Australia/Sydney"`

```json theme={"dark"}
{
  "clientId": "id",
  "dataAppName": "dataappname",
  "params": {
    "timezone": "America/New_York"
  }
}
```

### Code Examples

<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);
    ```
  </RequestExample>
</Panel>

### HTTP Status Codes

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

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

### Error Codes:

| Error Code                 | HTTP Status | Description                         |
| -------------------------- | ----------- | ----------------------------------- |
| `AUTHENTICATION_ERROR`     | 401         | Invalid or missing API key          |
| `INVALID_REQUEST_BODY`     | 400         | Missing or invalid parameters       |
| `CLIENT_ID_ERROR`          | 400         | Invalid clientId format or value    |
| `DATA_APP_ID_ERROR`        | 404         | Data app not found                  |
| `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                |
| `RATE_LIMIT_EXCEEDED`      | 429         | Too many requests                   |
| `INTERNAL_SERVER_ERROR`    | 500         | Server error                        |
| `INVALID_PERMISSIONS`      | 403         | Invalid permission settings         |
| `EXPIRED_TOKEN`            | 401         | Token has expired                   |