Understanding Embed Token Expiration and Authorization Flow in Bold BI

This article explains how AuthFlow works in Bold BI embedding and how token expiration behaves, helping you avoid issues such as unauthorized access or expired tokens in embedded dashboards.

Step-by- Step Guide

Note: The examples in this article are based on an ASP.NET Core Embedding sample application. The code samples may differ for other platforms. Refer to the platform-specific embedding documentation for implementation details.

Step 1: Identify Your Embedding Method

• Before troubleshooting authentication or token expiration issues, first identify the embedding method used in your application. The authentication workflow and token management process vary depending on whether you use JavaScript embedding or iframe embedding.

JavaScript Embedding (Recommended)

• Uses the Bold BI Embed SDK to render dashboards within a web application. Authentication is handled through a backend authorization endpoint that securely generates embed tokens.

BoldBI.create(...) 

Example of JavaScript embedding using the Bold BI Embed SDK with backend authorization configuration.

iframe Embedding

• Uses a generated embed URL to display the dashboard within an iframe. Security parameters such as timestamp, expiration, and signature values can be included in the URL to control access and token validity.

Step 2: Understand AuthFlow in Practice

• During AuthFlow, the Embed SDK sends a request to a backend authorization endpoint. The backend then calls the Bold BI /embed/authorize API, retrieves an embed token and expiration metadata, and returns the response to the client application for dashboard rendering.
  JavaScript Embedding Flow
• The frontend calls:

BoldBI.create(...) 

• The SDK triggers an Authorize API request via your backend
• Backend calls:
  /api/{siteIdentifier}/embed/authorize
• Bold BI returns:
  • access_token
  • Expiry details (expires_in, .expires)

Depending on the embedding implementation, the backend may return either the complete Authorize API response or only the generated embed token required by the client application.

• The frontend uses the token to render the dashboard
  Example: Token generation request sent to the ASP.NET Core backend application. The backend endpoint generates the embed token required to authorize and render the embedded dashboard.
  
  
  
  
  

Step 3: Understand Token Types

Embed Token (Authorize API Token)

• During the authorization flow, the backend application generates an embed token and returns it to the client application. This token is then used by the Embed SDK to authenticate the user and render the embedded dashboard. In the ASP.NET Core sample application, the token is returned from the TokenGeneration endpoint.
  
  

Example: The default ExpirationTime value configured in the ASP.NET Core embedding sample’s embedConfig.json file and used during embed token generation.

In the ASP.NET Core embedding sample, token expiration is controlled through the ExpirationTime setting in the embedConfig.json file. The sample uses a default value of 10000 seconds, which determines how long the generated embed token remains valid after issuance.

• When using the JavaScript Embed SDK, token expiration can also be specified through the expirationTime parameter during dashboard initialization. The maximum supported value is 7 days (604800 seconds).
  REST API Access Tokens
• REST API Access Tokens are used for API operations such as retrieving dashboard information, managing resources, and performing administrative actions. These tokens are independent of the embed tokens used for dashboard embedding.
• Not used for embedding

Step 4: Token Expiration Behavior

Default Expiration

• Embed tokens expire after 1 day (24 hours)

Custom Expiration

• You can configure expiry using:
  • expirationTime (JavaScript SDK)
• Maximum allowed:
  • 7 days (604800 seconds)
• Expiry Tracking
  The Authorize API response includes:

Best Practice:

• Use .expires to implement accurate refresh logic.

Step 5: Implement Token Rotation or Renewal Logic

• Embed tokens are temporary credentials. They do not remain valid forever, so your application should be designed to request a new token when needed.
  Recommended Strategy
• Generate tokens on the backend only
• Cache and reuse a valid token until it is near expiry
• Request a new token when the current one has expired or is about to expire
• Reinitialize or reload the embedded dashboard if your implementation requires a new token after expiry
• Example Logic

if current_time >= token_expiry_time:
   request_new_token()
   reload_dashboard() 

• This helps prevent:
  • unexpected unauthorized errors
  • repeated token generation on every request
  • inconsistent behavior during long-running sessions

Step 6: Backend Authorization Pattern for JavaScript Embedding

• Backend authorization endpoint performs these actions:
  • Accepts the dashboard and user context from the frontend or server-side config
  • Builds the embed authorization payload or query
  • Signs the request using the embed secret
  • Calls the Bold BI embed authorization endpoint
  • Returns the token needed by the frontend
    Example: Backend Token Generation (Concept)

app.post("/api/boldbi/authorize", async (req, res) => {
 // collect server URL, site identifier, dashboard details, and user context
 // sign the request using embedSecret on the server (HMACSHA256)
 // call Bold BI embed authorization endpoint
 // return the required token response to the client
 res.json({ access_token: "..." });
}); 

• Do not generate the signature or handle the embed secret in the browser. The backend authorization server is the secure bridge between the client application and Bold BI.

Step 7: iframe Embedding Expiration Controls

• When using iframe embedding, expiration is controlled via URL parameters:

Security Recommendations

• Use embed_nonce for anti-replay protection
• Apply domain/IP restrictions where possible

Common Issues & Fixes

Conclusion

Bold BI embedding relies on secure authorization patterns that vary depending on whether you use the JavaScript Embed SDK or iframe token authentication. In both cases, token handling should be implemented on the backend, and applications should be designed to account for token expiration and renewal.
By keeping secrets on the server, using the correct token type, and renewing tokens when needed, you can reduce unauthorized errors and provide a more stable embedded dashboard experience.

Related Articles

• How token expiration and rotation are handled in Bold BI
• Access Tokens: REST APIs vs. Authorize API in JS Embedding
• Secure Dashboard Embedding via Backend Authorization
• Bold BI Dashboard - JavaScript Embedding Token Generation
• Dashboard iframe Embedding with Token