ℹ️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 web component.

Create API key from Databrain's dashboard that should be passed in the headers in these requests.

---

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, workspaceName. If expiryTime is not passed, the token will not expire.

Cloud Databrain:

POST https://api.usedatabrain.com/api/v1/guest-token/create

Self-hosted Databrain:

POST <SELF_HOSTED_URL>/api/v1/guest-token/create

Generating GUEST TOKEN for your Dashboard/Metric Component.

Headers

Name	Type	Description
Authorization*	String	Bearer API TOKEN

Request Body

Name	Type	Description
workspaceName*	String	Your Workspace Name
clientId*	String	Client ID for whom this guest token is generated.
params	Object	Additional Params: dashboard appFilters
expiryTime	Number	In milli seconds

200: OK { "token": "..." }

when the response is successful it returns a token that you can pass to the frontend.

400: Bad Request {"error": {"message": "invalid dashboard id", "code": <ERROR_CODE> }}

When invalid parameter is passed, you will get this error. The "code" refers to the error code. Different types of error code that are possible are: 'INVALID_REQUEST_BODY'

'CLIENT_ID_ERROR'

'WORKSPACE_ID_ERROR'

'DASHBOARD_PARAM_ERROR'

'APP_FILTER_PARAM_ERROR'

'RLS_SETTINGS_PARAM_ERROR'

'INTERNAL_SERVER_ERROR'

401: Unauthorized {"error": {"message": "API key is invalid or expired", "code": "AUTHENTICATION_ERROR" }}

When the correct API key is not passed in the headers, you will get this error

Request Body Examples:

Simple Request Body:

{
  "clientId": "id",
  "workspaceName": "workspacename"
}

Request Body with Dashboard Specified:

{
  "clientId": "id",
  "workspaceName": "workspacename",
  "params" : {
     "dashboard": {
       "id": "dashboardid"
     }
   }
}

Request Body with App Level Metric Filter:

🛠️App filterGuides

{
  "clientId": "id",
  "workspaceName": "workspacename",
  "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 select)
			}
		}]
   }
}

A sample Postman Collection:

2KB

Request.json

Dashboard App Filters:

Request Body with Dashboard filters:

{
  "clientId": "id",
  "workspaceName": "workspacename",
  "params": {
    "dashboardAppFilters": [
      {
        "dashboardId": "dashboard-id",
        "values": {
          // single string
          "name": "Eric",
          // multi select
          "country": ["USA", "CANADA"] || "USA", // based on filter variant(select or multi select)
          // date-picker
          "timePeriod": { "startDate": "2024-01-01", "endDate": "2024-3-23" },
          // range
          "price": { "min": 1000, "max": 5000 }
        }
        "isShowOnUrl": true, // true/false
      }
    ]
  }
}

When you disable the isShowOnUrl the filter will not visible to end user as search params on URL.

Error Codes:

• 'AUTHENTICATION_ERROR'

• 'INVALID_REQUEST_BODY'

• 'CLIENT_ID_ERROR'

• 'WORKSPACE_ID_ERROR'

• 'DASHBOARD_PARAM_ERROR'

• 'APP_FILTER_PARAM_ERROR'

• 'RLS_SETTINGS_PARAM_ERROR'

• 'INTERNAL_SERVER_ERROR'