This page explains how to:
- Create YOUR OWN proxy endpoint on your backend server
- Configure the DataBrain component to use your proxy endpoint
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:- Receives authentication requests from DataBrain servers (with your proxy key)
- Validates user permissions using YOUR business logic
- Calls the DataBrain Guest Token API to generate a token
- 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):Your endpoint must be a GET endpointDataBrain servers will make GET requests to your proxy URL.
Your endpoint receives this header from DataBrain servers:Validate this header matches your configured proxy key before returning tokens.
Your endpoint receives this header: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: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.
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
Security Considerations
Authentication Best Practices
Authentication Best Practices
- 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
Error Handling
Error Handling
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
error object with code and message fields for consistent error handling.Token Caching
Token Caching
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 thewindow.dbn configuration before initializing the component.
Configuration Properties
The base URL of your DataBrain instance.
- Production:
https://app.usedatabrain.com - Self-hosted: Your DataBrain server URL
The full URL of your backend proxy endpoint that generates guest tokens.Example:
https://your-backend.com/api/databrain/guest-tokenA secret authentication key that DataBrain will send to your proxy endpoint as a Bearer token.
Enable or disable proxy authentication mode.
true: Use proxy authentication (required for proxy auth to work)falseor 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
Invalid Proxy Key
Invalid Proxy Key
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.Proxy Endpoint Not Reachable
Proxy Endpoint Not Reachable
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
Token Generation Failed
Token Generation Failed
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
User Not Authorized
User Not Authorized
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.
3
Update Frontend Configuration
Replace direct token generation with proxy configuration:Before:After:
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.

