Generate Embed Token Using Embed Secret and Pass User Context to Reports

When embedding reports into your application, it is common to manage users, roles, and permissions entirely within the application itself. In this approach, users sign in to the application using the organization’s existing authentication mechanism, and the application determines what information each user is authorized to access.

Bold Reports supports this architecture by allowing applications to securely access reports without requiring every application user to exist in the Report Server. Although a ReportServerUser is required during embed authentication, individual application users do not need to be created in Bold Reports. The Report Server manages report resources, data processing, report execution, and rendering, while your application continues to manage user authentication and authorization. User-specific context such as Customer ID, Employee ID, Department ID, Region, or Tenant ID can be passed through Custom Attributes and Report Parameters to ensure users only see the data they are authorized to access.

For embedded reporting scenarios, Bold Reports supports generating tokens using the Embed Authentication API and an Embed Secret Key, eliminating the need to expose Report Server user passwords to client 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 Case

Assume you have a CRM application that already manages users in its own authentication system.

Application User	Customer ID	Region
John Smith	CUST1001	North
David Miller	CUST2001	South

You do not want to create and maintain these users individually within Bold Reports.

Instead:

Users authenticate through your application.
Your application validates user permissions.
Your application generates an embed token using a dedicated Report Server user and an Embed Secret Key.
User-specific information is passed using Custom Attributes and Report Parameters.
The report uses those values to return only authorized data.

This approach keeps user management centralized within the application while allowing Bold Reports to securely render reports.

Generate an Embed Token

Step 1: Send a Token Generation Request

Send a POST request to the following endpoint.

Endpoint

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

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

For additional information, refer to the Embed Authentication API documentation:

https://help.boldreports.com/enterprise-reporting/rest-api-reference/embed-authentication/server-api-reference/#tag/Embed-Authentication

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": "Yhfw5o9c0VdPk8HWhQQnGKAl0K9HP",
  "ReportParameters": [
    {
      "Key": "FiscalYear",
      "Values": [
        "2026"
      ]
    },
    {
      "Key": "Currency",
      "Values": [
        "USD"
      ]
    }
  ],
  "CustomAttributes": [
    {
      "Key": "CustomerId",
      "Value": "CUST1001"
    },
    {
      "Key": "Region",
      "Value": "North"
    }
  ]
}

In this example:

FiscalYear and Currency are common report parameters that may be used across multiple reports.
CustomerId identifies the customer associated with the logged-in user.
Region restricts report data to a specific region.

Request Parameter Description

Parameter	Description
`grant_type`	Specifies the token type. Use `embed_token`.
`ReportServerUser`	Report Server user 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 user-specific values used for filtering and security 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

The following example shows a successful token generation response containing the generated access_token.

Figure: 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 applied during report execution, enabling the report to return data specific to the logged-in application user.

Using Custom Attributes for Data Security

Custom Attributes are commonly used to pass values that should be controlled by the application and not modified by end users. They are typically used to implement row-level security, tenant isolation, and user-specific data filtering.

Typical examples include:

Customer ID
Employee ID
Department ID
Tenant ID
Region
Branch ID

For example:

{
  "Key": "CustomerId",
  "Value": "CUST1001"
}

The dataset can consume the custom attribute and filter records accordingly:

SELECT *
FROM Orders
WHERE CustomerId = @CustomerId

Real-World Example

Consider a customer portal where all customers access the same embedded report.

When John logs in, the application generates a token with:

{
  "Key": "CustomerId",
  "Value": "CUST1001"
}

Only records belonging to customer CUST1001 are returned.

When David logs in, the application generates a token with:

{
  "Key": "CustomerId",
  "Value": "CUST2001"
}

The same report now returns only records belonging to customer CUST2001.

This enables user-specific data access while maintaining a single report definition for all users.

For information about configuring custom attributes within a dataset, refer to:

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

Using Report Parameters for Report Filtering

While Custom Attributes are typically used for security and authorization scenarios, 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

Unlike Custom Attributes, which are primarily used for user-specific security filtering, Report Parameters are generally used to provide common report filters that can be shared across multiple reports.

For example, an organization may want reports to default to the currently selected fiscal year and currency.

During token generation, the application can pass:

{
  "Key": "FiscalYear",
  "Values": [
    "2026"
  ]
},
{
  "Key": "Currency",
  "Values": [
    "USD"
  ]
}

Reports that contain matching report parameters automatically consume these values.

For example:

SELECT *
FROM Sales
WHERE FiscalYear = @FiscalYear

Real-World Example

Consider an enterprise portal containing multiple embedded reports:

Revenue Report
Sales Performance Report
Product Analysis Report
Regional Summary Report

The application generates a single embed token and includes:

"ReportParameters": [
    {
        "Key": "FiscalYear",
        "Values": ["2026"]
    },
    {
        "Key": "Currency",
        "Values": ["USD"]
    }
]

When a report contains a FiscalYear or Currency parameter, the values are automatically applied during report execution.

If a report does not contain one of these parameters, the value is ignored and the report continues to execute normally.

This allows organizations to generate a single token and reuse it across multiple reports without creating report-specific tokens.

Best Practice: Include commonly used report parameters during token generation. Reports with matching parameters consume the values, while reports that do not use those parameters simply ignore them. Generating separate embed tokens for individual reports solely to pass different parameter values is generally not the recommended approach.

In scenarios where users need to modify report parameters interactively, parameter values can be updated from the client side through the Report Viewer without regenerating the embed token. This allows reports to leverage default parameter values provided during token generation while still enabling end-user parameter interaction when required.

For information about setting report parameters from the Report Viewer, refer to:

https://help.boldreports.com/embedded-reporting/javascript-reporting/report-viewer/report-parameters/

For information about creating and configuring report parameters, refer to:

https://help.boldreports.com/enterprise-reporting/designer-guide/report-designer/report-parameters/add/

Recommended Architecture

For embedded reporting deployments:

Continue managing users and permissions within your application.
Generate embed tokens using a dedicated Report Server user and Embed Secret.
Pass user-specific security context through Custom Attributes.
Use Report Parameters for common report filtering requirements.
Configure datasets to consume these values and return only authorized data.
Reuse the generated token across embedded reports whenever applicable instead of generating report-specific tokens.

With this approach, individual application users do not need to be created within Bold Reports unless they require direct access to the Bold Reports Report Server portal. This provides a scalable and secure embedded reporting solution while keeping user management centralized in the host application.

Generate Embed Token Using Embed Secret and Pass User Context to Reports

Prerequisites

References

Practical Use Case

Generate an Embed Token

Step 1: Send a Token Generation Request

Endpoint

Step 2: Configure the Request Body

Example Request

Request Parameter Description

Step 3: Generate the Token

Sample Response

Sample Token Generation Response

Using the Generated Token in the Report Viewer

Using Custom Attributes for Data Security

Real-World Example

Using Report Parameters for Report Filtering

Real-World Example

Recommended Architecture

See Also

Access denied