Embedding API

Developer

The Embedding API allows Independent Software Vendors (ISVs) and enterprise developers to embed DataCentral reports directly into their own web applications or customer portals.

Instead of forcing your users to navigate to the DataCentral portal, you can request a secure, encrypted key from DataCentral and use it to render an iframe within your own application. DataCentral handles the complex Power BI authentication and Row-Level Security (RLS) behind the scenes.

---

1. How Embedding Works

The embedding process involves three steps:

1. Your Backend Server: Makes a secure API call to DataCentral, providing the user's identity, the report to embed, and any RLS roles to apply.
2. DataCentral: Verifies your API Key and Tenant Passphrase, communicates with Power BI to generate an embed token with the correct RLS context, and returns an encrypted key.
3. Your Frontend: Receives the encrypted key from your backend and constructs an iframe URL. DataCentral decrypts the key and renders the report securely inside the iframe.

Server-Side Only

The encryption endpoint must only be called from your backend server. Never expose your API Key or Tenant Passphrase in client-side code (JavaScript, mobile apps, etc.).

2. The Encryption Endpoint

Endpoint: POST https://api.{instancename}.datacentral.ai/v1/embed/encryption?apiKey={TENANT_API_KEY}

Replace {instancename} with your DataCentral instance name and {TENANT_API_KEY} with your Tenant's API Key.

Request Body

{
  "value": {
    "userId": "john.doe@example.com",
    "reportId": "e8a9c2f1-4b7d-4a1e-8f2c-9d3b5a6c7e8f",
    "roleNames": ["Region_EMEA", "Sales_Manager"],
    "expiration": "2026-02-01T13:30:00Z"
  },
  "passPhrase": "YOUR_TENANT_PASSPHRASE",
  "tenancyName": "yourtenant"
}

Request Body Fields

Field	Type	Required	Description
value.userId	string	Yes	The identity of the user viewing the report. This value is passed to Power BI and is used by DAX functions like USERNAME() and USERPRINCIPALNAME() for Dynamic RLS.
value.reportId	string	Yes	The DataCentral Item ID (GUID) of the report to embed.
value.roleNames	array of strings	No	An array of DataCentral RLS Role Codes to apply to the report session.
value.expiration	string (ISO 8601)	No	The expiration time for the encrypted key. Recommended for security. If omitted, the platform default applies.
passPhrase	string	Yes	Your Tenant's secret passphrase.
tenancyName	string	Yes	Your Tenant's subdomain name (e.g., acme for acme.datacentral.ai).

Example Request (cURL)

curl -X POST \
  "https://api.{instancename}.datacentral.ai/v1/embed/encryption?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "userId": "john.doe@example.com",
      "reportId": "e8a9c2f1-4b7d-4a1e-8f2c-9d3b5a6c7e8f",
      "roleNames": ["Region_EMEA"],
      "expiration": "2026-02-01T13:30:00Z"
    },
    "passPhrase": "YOUR_TENANT_PASSPHRASE",
    "tenancyName": "yourtenant"
  }'

Example Response

{
  "result": {
    "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "success": true,
  "error": null
}

3. Rendering the iframe

Once your backend server receives the encrypted key from result.key, pass it to your frontend. Construct the iframe URL using the following syntax:

<iframe
  src="https://{tenant}.datacentral.ai/report/{reportId}?ev={ENCRYPTED_KEY}"
  width="100%"
  height="800px"
  frameborder="0"
  allowfullscreen="true">
</iframe>

Replace {tenant} with your Tenant subdomain, {reportId} with the DataCentral report ID, and {ENCRYPTED_KEY} with the value from result.key.

4. Security Best Practices

• Server-side only: Always call the encryption endpoint from your backend. Never expose credentials in client-side code.
• Use a secret store: Store your API Key and Tenant Passphrase in a secure secrets manager (e.g., Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault). Do not hardcode them in your source code.
• Set short expiration windows: Use the expiration field to limit how long an embedded session is valid. For external-facing applications, 30–60 minutes is a reasonable default.
• Apply RLS roles: Always specify the appropriate roleNames to ensure users only see the data they are authorized to view.