Token Management
Route embed requests through your proxy
Send every embed request through your own server, so the browser never holds the guest token.
With proxy authentication, the embed sends its API requests to your server, not to Databrain. Your server checks the request, adds the guest token and forwards it to Databrain.
How it works
- The embed sends each request to
<proxyAuthUrl><path>, without the guest token. - The request carries your key in
X-Proxy-Auth-KeyandX-Authorization. - Your proxy checks the key, adds
X-Plugin-Token: <guest token>and forwards the request tohttps://api.usedatabrain.com<path>. - Your proxy returns Databrain’s response as it is.
Steps
- Set
window.dbnbefore the embed loads:
<script>
window.dbn = {
...window.dbn,
isEnableProxyAuth: true,
proxyAuthUrl: 'https://analytics-proxy.example.com',
proxyAuthKey: 'SESSION_KEY_FOR_THIS_USER',
};
</script>
<dbn-dashboard dashboard-id="YOUR_DASHBOARD_ID"></dbn-dashboard>-
Build the proxy. For each request it must:
- Read
X-Proxy-Auth-Key(orX-Authorization) and check it against the user’s session. Refuse with 401 or 403 if it is wrong. - Create or look up the guest token for that user on your server.
- Forward the same method, path, query string and body to
https://api.usedatabrain.com. - Add
X-Plugin-Token: <guest token>. - Forward these headers as they arrive:
Origin,Content-Type,X-Plugin-Origin,X-Proxy-Auth-Key,X-Proxy-Auth-Url,X-Authorization,X-Dbn-Plugin-VersionandX-Dbn-Plugin-Contract. - Return the status, headers and body unchanged. Some responses are files (CSV, PDF, Excel), so do not parse the body.
- Read
-
Allow your app’s origin in your proxy’s CORS settings.
The dashboard now loads through your proxy. The browser’s network tab shows no guest token.
Request headers the embed sends
| Header | Value |
|---|---|
X-Proxy-Auth-Key | window.dbn.proxyAuthKey |
X-Authorization | window.dbn.proxyAuthKey |
X-Proxy-Auth-Url | window.dbn.proxyAuthUrl |
X-Plugin-Origin | The host of your page |
X-Dbn-Plugin-Version | The plugin build |
X-Dbn-Plugin-Contract | The plugin’s API contract number |
When proxy mode is on, the embed does not send X-Plugin-Token. When Databrain sees the proxy headers, it encrypts the guest token inside the dashboard response.
About proxyAuthKey
proxyAuthKey is in browser JavaScript, so anyone using the page can read it. Use a value that belongs to one signed-in session and that your proxy can check, such as a short-lived session token. Do not use a fixed secret shared by all users.
If something goes wrong
- Nothing loads and no request is sent. Set both
proxyAuthUrlandproxyAuthKeywhenisEnableProxyAuthistrue. - 400 “UNAUTHORISED REQUEST!” from Databrain. Your proxy did not add
X-Plugin-Token, or the token is not a valid guest token. - 403
UNAUTHORIZED_ORIGIN. ForwardX-Plugin-Originand the browser’sOrigin, and add your app’s domain to the whitelisted domains.
Related: Security.