Skip to Content

Token Management

Move guest tokens from v1 to v2

Change your backend from POST /api/v1/guest-token/create to the data app based v2 endpoint.

v2 creates guest tokens for a data app, not a workspace. The body is not the same, so changing the URL is not enough.

What changes

v1v2
EndpointPOST /api/v1/guest-token/createPOST /api/v2/guest-token/create
Names the content byworkspaceName (required)dataAppName (required)
API keyA company keyThe API key of that data app
params.dashboard (id, mode)YesGone. Use params.allowedEmbeds.
datamartNameNoYes
params.userIdentifier, timezone, allowedEmbeds, hideDashboardMetricsNoYes
accessPermissions.isAllowAutoClientScopeNoYes
permissions.isDisableMetricCreationNoYes

clientId, datasourceName, expiryTime, rlsSettings, appFilters, dashboardAppFilters, tableAppFilters, hideDashboardFilters and the other permissions keep the same shape.

Before you start

  • Your dashboards are in a data app. Go to Data Studio > Data Apps to check.
  • You have that data app’s API key. Open the data app and go to API token.

Steps

  1. Change the URL to https://api.usedatabrain.com/api/v2/guest-token/create.
  2. Send the data app API key: Authorization: Bearer <data app API key>.
  3. Replace workspaceName with dataAppName, the data app’s exact saved name.
  4. If you sent params.dashboard.id, send params.allowedEmbeds: ["<dashboard id>"] instead.
  5. Add params.userIdentifier with your user’s ID or email.

Before:

{
  "clientId": "acme-corp",
  "workspaceName": "Sales Workspace",
  "params": { "dashboard": { "id": "YOUR_DASHBOARD_ID" } }
}

After:

{
  "clientId": "acme-corp",
  "dataAppName": "Customer Analytics",
  "params": {
    "allowedEmbeds": ["YOUR_DASHBOARD_ID"],
    "userIdentifier": "jane@acme.example"
  }
}

The response is the same shape: { "token": "<guest token>", "expireAt": "<ISO time>" }. The front end does not change.

Expiry

Both versions default to 24 hours when you leave out expiryTime. Tokens never live forever. Existing v1 tokens keep working until they expire.

If something goes wrong

  • 403 INVALID_DATA_APP_API_KEY: “This API key belongs to a data app. Use POST /api/v2/guest-token/create with dataAppName to create a guest token for it.” You sent a data app key to v1, and this rule is on for your company. Move to v2.
  • 400 AUTHENTICATION_ERROR. The API key is not the key of the data app in dataAppName.
  • 400 INVALID_DATA_APP_NAME: “invalid data app name, data app name not found”. dataAppName must match the saved name exactly.
  • 400 INVALID_REQUEST_BODY: "workspaceName" is not allowed. Remove workspaceName from the v2 body.

See Token body for every v2 field.