Skip to main content
This page explains how to:
  1. Create YOUR OWN proxy endpoint on your backend server
  2. Configure the DataBrain component to use your proxy endpoint
This is different from the Guest Token API which documents a DataBrain API endpoint.
Proxy authentication lets your backend handle the secure retrieval and delivery of guest tokens to DataBrain, rather than passing tokens directly from your frontend code. This improves security by ensuring sensitive credentials stay on your server, enabling DataBrain embedding without exposing tokens to the client.
Enhanced Security: With proxy authentication, your frontend never directly handles API keys. Instead, your backend server manages authentication and returns guest tokens only to authorized users.

How Proxy Authentication Works

1

Configure Your Backend Proxy

Set up an endpoint on your backend server that generates and returns DataBrain guest tokens. This endpoint should validate user permissions before issuing tokens.
2

Configure Frontend Component

Update your DataBrain component configuration to use proxy authentication by providing your proxy URL and authentication key.
3

Authentication Flow

When the DataBrain component needs a guest token, it sends a request to DataBrain servers with your proxy credentials. DataBrain then calls your proxy endpoint to fetch the token.
4

Token Returned

Your proxy returns a guest token (UUID format), which DataBrain uses to render the embedded dashboard or metrics.

Backend Configuration

You create this endpoint on YOUR backend server. This is not a DataBrain API - you implement this endpoint yourself to control token generation and user authorization.

Setting Up Your Proxy Endpoint

Create a GET endpoint on your backend that returns guest tokens. This endpoint will be called by DataBrain servers to fetch tokens for your users. What this endpoint does:
  1. Receives authentication requests from DataBrain servers (with your proxy key)
  2. Validates user permissions using YOUR business logic
  3. Calls the DataBrain Guest Token API to generate a token
  4. Returns the token to DataBrain servers
Your proxy endpoint must return a JSON response with either a token field (UUID format guest token) or an error object.

Your Proxy Endpoint Specification

Your backend endpoint must meet these specifications (DataBrain servers will call YOUR endpoint with these requirements):
HTTP Method
string
required
Your endpoint must be a GET endpointDataBrain servers will make GET requests to your proxy URL.
Authorization Header
string
required
Your endpoint receives this header from DataBrain servers:
Authorization: Bearer {your-proxy-key}
Validate this header matches your configured proxy key before returning tokens.
Content-Type Header
string
Your endpoint receives this header:
Content-Type: application/json
DataBrain servers send this header with every request to your proxy.

Response Format (What YOUR Endpoint Returns)

Your proxy endpoint must return one of these response formats to DataBrain servers: Success Response:
{
  "token": "550e8400-e29b-41d4-a716-446655440000"
}
token
string
required
Your endpoint returns this on success: A valid guest token in UUID format.Generate this token by calling the DataBrain Guest Token API from your backend.
Error Response:
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "User not authorized to access this resource"
  }
}
error
object
Your endpoint returns this on error: Error object with code and message fields.DataBrain will forward this error to the frontend, so use clear, user-friendly messages.

Example Implementations

  • Node.js/Express
  • Python/Flask
  • Java/Spring Boot
// Create this endpoint on YOUR backend server
// This is YOUR custom endpoint, not a DataBrain API
app.get('/api/databrain/guest-token', async (req, res) => {
  try {
    // Verify the request is from DataBrain using the auth key
    const authHeader = req.headers.authorization;
    if (!authHeader || authHeader !== `Bearer ${process.env.DATABRAIN_PROXY_KEY}`) {
      return res.status(401).json({
        error: {
          code: 'UNAUTHORIZED',
          message: 'Invalid authentication key'
        }
      });
    }

    // Add your own authorization logic here
    // For example, check user session, permissions, etc.
    const userSession = req.session?.user;
    if (!userSession) {
      return res.status(401).json({
        error: {
          code: 'UNAUTHORIZED',
          message: 'User not authenticated'
        }
      });
    }

    // Generate guest token using DataBrain API
    // Note: You can also return an existing/cached guest token instead of generating a new one each time
    const response = await fetch('https://api.usedatabrain.com/api/v2/guest-token/create', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.DATABRAIN_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        clientId: userSession.id,
        dataAppName: 'your-data-app-name',
        // Add any additional parameters like filters, permissions, etc.
      })
    });

    const data = await response.json();

    if (data.error) {
      return res.status(400).json({ error: data.error });
    }

    // Return the guest token
    res.json({ token: data.token });
  } catch (error) {
    console.error('Error generating guest token:', error);
    res.status(500).json({
      error: {
        code: 'INTERNAL_ERROR',
        message: 'Failed to generate guest token'
      }
    });
  }
});

Security Considerations

  • Use Strong Keys: Generate a strong, random proxy authentication key
  • Validate Requests: Always verify the authorization header matches your proxy key
  • Check User Permissions: Implement your own authorization logic before issuing tokens
  • Rate Limiting: Add rate limiting to prevent abuse of your proxy endpoint
  • HTTPS Only: Ensure your proxy endpoint is only accessible via HTTPS
  • Log Access: Keep audit logs of all token generation requests
Your proxy should return appropriate error responses:
  • 401 Unauthorized: When authentication fails
  • 403 Forbidden: When user lacks permissions
  • 500 Internal Server Error: When token generation fails
Always include an error object with code and message fields for consistent error handling.
Consider implementing token caching to reduce API calls:
  • Cache guest tokens for their validity period
  • Implement cache invalidation when user permissions change
  • Use user-specific cache keys to prevent token leakage

Frontend Configuration

DataBrain Component Setup

Configure your DataBrain component to use proxy authentication by setting the window.dbn configuration before initializing the component.
import { Databrain } from '@databrainhq/plugin';

// Configure proxy authentication globally
if (typeof window !== 'undefined') {
  window.dbn = {
    baseUrl: 'https://app.usedatabrain.com',
    proxyAuthUrl: 'https://your-backend.com/api/databrain/guest-token',
    proxyAuthKey: 'your-proxy-authentication-key',
    isEnableProxyAuth: true
  };
}

function MyDashboard() {
  return (
    <Databrain
      dashboardId="your-dashboard-id"
      // Note: No token prop needed with proxy auth
    />
  );
}

Configuration Properties

window.dbn.baseUrl
string
required
The base URL of your DataBrain instance.
  • Production: https://app.usedatabrain.com
  • Self-hosted: Your DataBrain server URL
window.dbn.proxyAuthUrl
string
required
The full URL of your backend proxy endpoint that generates guest tokens.Example: https://your-backend.com/api/databrain/guest-token
This URL must be accessible from DataBrain servers, not from the browser. Ensure proper CORS and firewall rules are configured.
window.dbn.proxyAuthKey
string
required
A secret authentication key that DataBrain will send to your proxy endpoint as a Bearer token.
Generate a strong, random key and store it securely on both your frontend and backend. This key should match the one your backend expects in the Authorization header.
window.dbn.isEnableProxyAuth
boolean
required
Enable or disable proxy authentication mode.
  • true: Use proxy authentication (required for proxy auth to work)
  • false or omitted: Use direct token authentication

Authentication Flow

The following diagram illustrates how proxy authentication works:

Error Handling

When proxy authentication fails, DataBrain will display the error returned by your proxy endpoint.

Common Errors

Error: 401 Unauthorized - Invalid authentication keyCause: The proxy key in your frontend configuration doesn’t match the key expected by your backend.Solution: Verify that window.dbn.proxyAuthKey matches the key your backend validates.
Error: Network error or timeoutCause: DataBrain servers cannot reach your proxy endpoint.Solution:
  • Ensure your proxy endpoint is publicly accessible
  • Check firewall rules and CORS configuration
  • Verify the URL is correct
Error: Varies based on your implementationCause: Your backend failed to generate a guest token from DataBrain API.Solution:
  • Check your DataBrain API key is valid
  • Verify the request parameters (clientId, dataAppName, etc.)
  • Review server logs for detailed error messages
Error: Custom error from your backendCause: User doesn’t have permission to access the dashboard.Solution: This is expected behavior. Ensure your authorization logic correctly identifies authorized users.

Migration from Direct Token Authentication

If you’re currently using direct token authentication, follow these steps to migrate to proxy authentication:
1

Create Proxy Endpoint

Set up your backend proxy endpoint using one of the examples above.
2

Generate Proxy Key

Create a strong, random authentication key for your proxy endpoint.
# Generate a random key (example)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
3

Update Frontend Configuration

Replace direct token generation with proxy configuration:Before:
<Databrain
  dashboardId="dashboard-123"
  token="guest-token-here"
/>
After:
window.dbn = {
  baseUrl: 'https://app.usedatabrain.com',
  proxyAuthUrl: 'https://your-backend.com/api/databrain/guest-token',
  proxyAuthKey: 'your-proxy-key',
  isEnableProxyAuth: true
};

<Databrain
  dashboardId="dashboard-123"
  // No token prop needed
/>
4

Test Thoroughly

Test the proxy authentication flow in a staging environment before deploying to production.
5

Monitor

Set up monitoring and logging for your proxy endpoint to catch any issues early.