Skip to content
Volidator Docs

Embedding the Dashboard

The dashboard widget lets your customers view their own audit logs inside your product. Logs are decrypted in the browser. Your server and Volidator’s server never see the decryption key.

Prerequisites

Section titled “Prerequisites”

You need projectId and clientSecret from the Volidator dashboard. Add them to your constructor:

const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
  projectId: process.env.VOLIDATOR_PROJECT_ID!,
  clientSecret: process.env.VOLIDATOR_CLIENT_SECRET!,
});

Generate an embed token

Section titled “Generate an embed token”

Call generateEmbedToken() in a server-side route. Do not call it on the client.

const { embedUrl } = await volidator.generateEmbedToken({
  actorId: session.userId,   // the user whose logs to show
  expiresIn: '2h',           // how long the token is valid
});

embedUrl looks like:

The `#{encryptionKey}` hash fragment is appended automatically. Browsers never send it to the server.


## Customizing Columns and Views


Developers can pre-configure the presentation layout of the log grid view directly from their server codebase by passing a `view` object to `generateEmbedToken()`.


When a signed `view` presentation configuration is present in the JWT, the column customizer inside the embedded iframe is disabled completely to preserve the publisher's intended column layout:


```ts
const { embedUrl } = await volidator.generateEmbedToken({
  actorId: session.userId,
  expiresIn: '2h',
  view: {
    // Render standard fields and pin dynamic decrypted metadata paths
    columns: ['timestamp', 'actor', 'action', 'metadata.plan_level'],
    defaultFilter: {
      action: 'BILLING.UPGRADED',
    }
  }
});

For more details, see the generateEmbedToken() Reference.

Add the iframe

Section titled “Add the iframe”

Pass embedUrl to your frontend and render it in an <iframe>:

// Next.js example
export default async function AuditLogPage() {
  const { embedUrl } = await volidator.generateEmbedToken({
    actorId: session.userId,
    expiresIn: '2h',
  });


  return (
    <iframe
      src={embedUrl}
      width="100%"
      height="600"
      style={{ border: 'none', borderRadius: '8px' }}
      title="Audit Log"
    />
  );
}

Token expiry

Section titled “Token expiry”

The JWT expires after the duration set in expiresIn. After expiry, the iframe redirects to an expiry page. Re-generate the token on each page load to keep it fresh.

Supported duration formats:

Format Duration
30s 30 seconds
15m 15 minutes
2h 2 hours
7d 7 days

Security considerations

Section titled “Security considerations”
  • Generate the embed URL on the server, never in the browser.
  • Do not log or cache the full embedUrl. The hash fragment contains the encryption key.
  • Use a short expiresIn (1h to 2h) for session-bound embeds.
Section titled “Related”