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
| v1 | v2 | |
|---|---|---|
| Endpoint | POST /api/v1/guest-token/create | POST /api/v2/guest-token/create |
| Names the content by | workspaceName (required) | dataAppName (required) |
| API key | A company key | The API key of that data app |
params.dashboard (id, mode) | Yes | Gone. Use params.allowedEmbeds. |
datamartName | No | Yes |
params.userIdentifier, timezone, allowedEmbeds, hideDashboardMetrics | No | Yes |
accessPermissions.isAllowAutoClientScope | No | Yes |
permissions.isDisableMetricCreation | No | Yes |
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
- Change the URL to
https://api.usedatabrain.com/api/v2/guest-token/create. - Send the data app API key:
Authorization: Bearer <data app API key>. - Replace
workspaceNamewithdataAppName, the data app’s exact saved name. - If you sent
params.dashboard.id, sendparams.allowedEmbeds: ["<dashboard id>"]instead. - Add
params.userIdentifierwith 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 indataAppName. - 400
INVALID_DATA_APP_NAME: “invalid data app name, data app name not found”.dataAppNamemust match the saved name exactly. - 400
INVALID_REQUEST_BODY:"workspaceName" is not allowed. RemoveworkspaceNamefrom the v2 body.
See Token body for every v2 field.