Embedding Reports Using Embed Tokens with Custom Attributes and Report Parameters in Bold Reports

When embedding reports into an application, the application must authenticate requests sent to the Bold Reports Report Server. For embedded reporting scenarios, Bold Reports provides Embed Secret Authentication, which enables applications to securely generate embed tokens without exposing Report Server user passwords.

In addition to authentication, embedded reports often require contextual information that influences how data is retrieved, filtered, or secured during report execution. Depending on the application’s architecture, this context may already exist within the host application and not within Bold Reports.

Using the Embed Authentication API, applications can generate embed tokens and pass application-specific and user-specific context through Custom Attributes and Report Parameters. These values can represent Tenant ID, Customer ID, Employee ID, Department ID, Region, Branch ID, Database Name, API Authentication Token, Organization Code, Business Unit, or any other identifier required by the application’s reporting architecture.

This article explains how to generate embed tokens using Embed Secret Authentication and use Custom Attributes and Report Parameters to provide contextual information during report execution.

Authentication Model

In this approach, the host application is responsible for user authentication and authorization, while Bold Reports is responsible for report processing, data processing, report execution, and rendering.

During token generation, the application can pass contextual values through Custom Attributes and Report Parameters. Reports and datasets can then consume these values to implement tenant isolation, row-level security, API authentication, dynamic connections, user-specific filtering, and other business-specific requirements.

This architecture enables organizations to maintain a centralized authentication and authorization system while securely embedding reports in external applications.

Prerequisites

Before generating an embed token, ensure that:

You have access to a Bold Reports Report Server environment.
An Embed Secret Key has been generated.

References

Embed Authentication API
https://help.boldreports.com/enterprise-reporting/rest-api-reference/embed-authentication/server-api-reference/#tag/Embed-Authentication
Get Embed Secret Code
https://help.boldbi.com/site-administration/embed-settings/#get-embed-secret-code

Practical Use Cases

Different applications use different approaches to control data access and report execution. The following examples illustrate common values that can be passed through Custom Attributes and Report Parameters during embed token generation.

Scenario	Value Passed
Multi-tenant SaaS application	Tenant ID
Customer portal	Customer ID
Employee self-service application	Employee ID
Department-based reporting	Department ID
Regional reporting application	Region
Branch-based reporting	Branch ID
Database-per-customer architecture	Database Name
API-based data source integration	API Authentication Token
Enterprise applications	Organization Code or Business Unit

Generate an Embed Token

Step 1: Send a Token Generation Request

Endpoint

{BoldReportsUrl}/reporting/api/site/{tenant-name}/token

Note: Replace {BoldReportsUrl} and {tenant-name} with your Report Server details.

Step 2: Configure the Request Body

The request body can include:

Report Server User
Embed Secret
Report Parameters
Custom Attributes

Example Request

{
"grant_type": "embed_token",
"ReportServerUser": "[email protected]",
"Embed_Secret": "your-embed-secret",
"ReportParameters": [
{
"Key": "FiscalYear",
"Values": ["2026"]
}
],
"CustomAttributes": [
{
"Key": "TenantId",
"Value": "TENANT001"
},
{
"Key": "ApiAuthenticationToken",
"Value": "generated-api-token"
}
]
}

Example Explanation

In this example:

FiscalYear is a Report Parameter used to control report output.
TenantId identifies the tenant associated with the current user.
ApiAuthenticationToken can be used by API-based data sources to authenticate requests against external services during dataset execution.

Depending on the application’s architecture, these values may represent Customer IDs, Regions, Database Names, Employee IDs, Business Units, Organization Codes, or other application-specific information.

Request Parameter Description

Parameter	Description
`grant_type`	Specifies the token type. Use `embed_token`.
`ReportServerUser`	Report Server user account used to generate the embed token.
`Embed_Secret`	Embed Secret Key associated with the Report Server user.
`ReportParameters`	Optional report parameter values applied during report execution.
`CustomAttributes`	Optional application-specific and user-specific values used for filtering, security, API authentication, and data-access scenarios.

Note: When using the Embed_Secret field, the Password field is not required.

Step 3: Generate the Token

Send the request to the token endpoint.

A successful response returns the generated token in the access_token field.

Sample Response

{
"access_token": "generated_embed_token",
"token_type": "bearer",
"expires_in": 86400
}

Sample Token Generation Response

Figure: Successful embed token generation response.

Successful embed token generation response

The value returned in the access_token field is used as the embedToken while loading reports in the Bold Reports Viewer.

Using the Generated Token in the Report Viewer

After generating the token, use the value returned in the access_token field as the embedToken property while initializing the Bold Reports Viewer.

$("#report-viewer").boldReportViewer({
reportServiceUrl: "http://reportserver.syncfusion.com/ReportService/api/Viewer",
reportPath: report_path,
embedToken: generated_access_token
});

The Report Viewer uses the token to authenticate the request and render the report. Any Report Parameters and Custom Attributes included during token generation are automatically available during report execution.

Passing User Context Through Custom Attributes

Custom Attributes are commonly used to pass values that should be controlled by the application and not modified by end users. They are useful for tenant isolation, row-level security, API authentication, dynamic data routing, runtime configuration, and user-specific filtering.

Common examples include:

Tenant ID
Customer ID
Employee ID
Department ID
Region
Branch ID
Database Name
Organization Code
Business Unit
API Authentication Token

API Data Source Scenario

{
"Key": "ApiAuthenticationToken",
"Value": "generated-api-access-token"
}

When using API data sources, the custom attribute can be consumed during dataset execution to authenticate requests against external APIs and retrieve tenant-specific or user-specific data.

For more information, refer to:

https://help.boldreports.com/enterprise-reporting/designer-guide/report-designer/manage-data/dataset/configure-custom-attribute/

Using Report Parameters for Report Filtering

Report Parameters are commonly used to control report output based on business requirements.

Typical examples include:

Fiscal Year
Date Range
Currency
Country
Business Unit
Product Category
Language

Reports that contain matching parameters automatically consume the values passed during token generation.