Skip to Content

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

  1. The embed sends each request to <proxyAuthUrl><path>, without the guest token.
  2. The request carries your key in X-Proxy-Auth-Key and X-Authorization.
  3. Your proxy checks the key, adds X-Plugin-Token: <guest token> and forwards the request to https://api.usedatabrain.com<path>.
  4. Your proxy returns Databrain’s response as it is.

Steps

  1. Set window.dbn before 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>
  1. Build the proxy. For each request it must:

    • Read X-Proxy-Auth-Key (or X-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-Version and X-Dbn-Plugin-Contract.
    • Return the status, headers and body unchanged. Some responses are files (CSV, PDF, Excel), so do not parse the body.
  2. 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

HeaderValue
X-Proxy-Auth-Keywindow.dbn.proxyAuthKey
X-Authorizationwindow.dbn.proxyAuthKey
X-Proxy-Auth-Urlwindow.dbn.proxyAuthUrl
X-Plugin-OriginThe host of your page
X-Dbn-Plugin-VersionThe plugin build
X-Dbn-Plugin-ContractThe 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 proxyAuthUrl and proxyAuthKey when isEnableProxyAuth is true.
  • 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. Forward X-Plugin-Origin and the browser’s Origin, and add your app’s domain to the whitelisted domains.

Related: Security.