Tool Integration Guide

Developer & ISV

This guide explains how to build a web application that integrates with DataCentral's tool embedding feature. When your application is embedded as a tool inside DataCentral, it can receive session data, authentication tokens, and Power BI tokens.

1. Session Data via URL

When DataCentral loads your tool in an iframe, it appends two query parameters to your URL:

Parameter	Description
`dcdata`	Base64-encoded JSON containing the user's session context.
`dcsig`	HMAC-SHA256 signature of the `dcdata` value.

Session Data Structure

{
  "userId": 3,
  "userName": "admin",
  "userDisplayName": "John Doe",
  "tenancyName": "acme",
  "tenantId": 1,
  "roleDisplayNames": ["Admin", "Viewer"],
  "roleIds": [2, 8],
  "clientUrl": "https://acme.datacentral.ai",
  "timeStamp": "2026-06-22T12:00:00Z"
}

Verifying the Signature

To verify the session data hasn't been tampered with, compute an HMAC-SHA256 of the dcdata value using the shared secret configured in the tool settings. Compare the result with the dcsig parameter.

// Example: Node.js verification
const crypto = require('crypto');

const dcdata = new URLSearchParams(window.location.search).get('dcdata');
const dcsig = new URLSearchParams(window.location.search).get('dcsig');

const expectedSig = crypto
  .createHmac('sha256', YOUR_SHARED_SECRET)
  .update(dcdata)
  .digest('base64');

const isValid = expectedSig === dcsig;

Verifying the signature via the API

Instead of computing the signature locally, you can use DataCentral's built-in API endpoint to generate the expected signature and compare it against the received dcsig.

POST /api/services/app/SidebarItems/GenerateToolSignature

This endpoint is publicly accessible and does not require authentication.

Request Body

{
  "data": "eyJ1c2VySWQiOjMsInVzZXJOYW1lIjoiYWRtaW4iLC4uLn0=",
  "key": "your-tool-shared-secret"
}

Field	Type	Description
`data`	`string`	The `dcdata` value (raw Base64 string).
`key`	`string`	The shared secret configured in the tool settings.

Response

The endpoint returns the HMAC-SHA256 signature as a Base64 string. Compare this against the dcsig value you received.

Example

async function verifyWithApi(dcdata, dcsig, secret, tenantUrl) {
  const response = await fetch(
    `${tenantUrl}/api/services/app/SidebarItems/GenerateToolSignature`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ data: dcdata, key: secret })
    }
  );

  const expectedSig = await response.json();
  return expectedSig === dcsig;
}

tip

For high-throughput applications, prefer local HMAC-SHA256 verification to avoid the extra network round-trip.

2. Token Forwarding via postMessage

If the tool administrator has enabled token forwarding, your application can receive authentication tokens from DataCentral via the browser's postMessage API.

Step 1: Send AppReady

When your application has loaded and is ready to receive tokens, send an AppReady message to the parent window:

window.parent.postMessage({ type: 'AppReady' }, '*');

Step 2: Listen for Tokens

DataCentral will respond with a message containing the configured tokens:

window.addEventListener('message', (event) => {
  // Ignore messages from other sources (e.g. browser extensions)
  if (!event.data || typeof event.data !== 'object') return;
  if (!event.data.accessToken && !event.data.graphToken && !event.data.pbiToken && !event.data.pbiProToken) return;

  const { accessToken, graphToken, pbiToken, pbiProToken } = event.data;

  // accessToken  — DataCentral JWT (if "Include Access Token" is enabled)
  // graphToken   — Microsoft Graph API token (if "Include Graph Token" is enabled)
  // pbiToken     — Power BI API token from service principal (if "Include PBI Token" is enabled)
  // pbiProToken  — Power BI Pro token from user's AAD session (if auth app supports PBI)
});

Token Reference

Token	Key	Source	Requires Auth
DataCentral JWT	`accessToken`	User's session cookie	Yes
Microsoft Graph	`graphToken`	MSAL `acquireTokenSilent` / `loginPopup`	Yes (AAD user)
PBI Service Principal	`pbiToken`	Server-side client_credentials flow	No
PBI Pro (user)	`pbiProToken`	MSAL `acquireTokenSilent`	Yes (AAD user with PBI-enabled auth app)

note

The pbiProToken is only included when the selected authentication app has Power BI permissions (Authentication 2 or 3). It is separate from pbiToken, which uses a service principal and does not require the user to have a Power BI Pro license.

3. Using the Tokens

DataCentral API

Use the accessToken as a Bearer token to call DataCentral API endpoints:

fetch('https://api.acme.datacentral.ai/api/services/app/...', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Abp.TenantId': '1'
  }
});

Microsoft Graph API

Use the graphToken to call Microsoft Graph endpoints:

fetch('https://graph.microsoft.com/v1.0/me', {
  headers: { 'Authorization': `Bearer ${graphToken}` }
});

Power BI REST API

Use either pbiToken (service principal) or pbiProToken (user's Pro license) to call the Power BI REST API:

// List reports in a workspace
fetch('https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/reports', {
  headers: { 'Authorization': `Bearer ${pbiToken}` }
});

4. Minimal Test Page

Use this HTML page to test your tool integration. Host it on a local server and configure it as a tool URL in DataCentral.

<!DOCTYPE html>
<html>
<head>
    <title>Tool Test</title>
    <style>
        body { font-family: monospace; padding: 20px; }
        .token { background: #f0f0f0; padding: 10px; margin: 8px 0;
                 word-break: break-all; max-height: 80px; overflow-y: auto; }
        .label { font-weight: bold; }
    </style>
</head>
<body>
    <h2>Tool Embed Test</h2>
    <p id="status">Waiting for tokens...</p>

    <div class="label">accessToken</div>
    <div class="token" id="accessToken">-</div>

    <div class="label">graphToken</div>
    <div class="token" id="graphToken">-</div>

    <div class="label">pbiToken</div>
    <div class="token" id="pbiToken">-</div>

    <div class="label">pbiProToken</div>
    <div class="token" id="pbiProToken">-</div>

    <script>
        window.addEventListener('message', (event) => {
            if (!event.data || typeof event.data !== 'object') return;
            if (!event.data.accessToken && !event.data.graphToken
                && !event.data.pbiToken && !event.data.pbiProToken) return;

            document.getElementById('status').textContent = 'Tokens received!';
            document.getElementById('accessToken').textContent = event.data.accessToken || '-';
            document.getElementById('graphToken').textContent = event.data.graphToken || '-';
            document.getElementById('pbiToken').textContent = event.data.pbiToken || '-';
            document.getElementById('pbiProToken').textContent = event.data.pbiProToken || '-';
        });

        window.parent.postMessage({ type: 'AppReady' }, '*');
    </script>
</body>
</html>

5. Security Considerations

Origin validation — DataCentral validates the origin of incoming AppReady messages against your tool's configured URL. Messages from other origins are ignored.
Token scope — The Graph token's permissions are determined by the Entra ID app registration selected by the administrator, not by your application. You cannot request additional scopes.
Token expiration — All tokens have limited lifetimes (typically 1 hour). If your tool is long-running, you may need to request fresh tokens by sending another AppReady message.
Public embeds — When your tool is accessed via a public link (no authenticated user), only the pbiToken (service principal) is available. The accessToken, graphToken, and pbiProToken require an authenticated user session.

1. Session Data via URL​

Session Data Structure​

Verifying the Signature​

Verifying the signature via the API​

Request Body​

Response​

Example​

2. Token Forwarding via postMessage​

Step 1: Send AppReady​

Step 2: Listen for Tokens​

Token Reference​

3. Using the Tokens​

DataCentral API​

Microsoft Graph API​

Power BI REST API​

4. Minimal Test Page​

5. Security Considerations​