Skip to content
Volidator Docs

generateEmbedToken()

generateEmbedToken() generates a signed HS256 JWT and an embed URL that contains the actor’s blind index. Call this server-side. Do not expose the result on the client before passing it to an iframe.

Requires projectId and clientSecret in the constructor config.

Signature

Section titled “Signature”
async generateEmbedToken(config: EmbedTokenConfig): Promise<EmbedTokenResult>

EmbedTokenConfig

Section titled “EmbedTokenConfig”
Name Type Required Default Description
actorId string No The actor identifier whose logs to display. One of actorId, targetId, or tenantId must be provided.
targetId string No The target resource identifier whose logs to display.
tenantId string No The tenant/organization identifier whose logs to display.
scope string No The query scope restriction. Options: 'actor', 'target', 'tenant', or 'all'. Defaults to 'tenant' if tenantId is provided, otherwise 'actor'.
expiresIn string No '2h' Token lifetime. Cap/max is 1 hour for security. Supports s, m, h, d suffixes. Example: '30m'.
dashboardUrl string No 'https://dash.volidator.com' Base URL of the dashboard. Override if using a custom dashboard domain.
hostOrigin string No The exact origin of the parent app embedding the iframe (e.g., https://app.example.com). Enables strict postMessage origin checks in JIT Hydration.
view EmbedViewConfig No Enforces a pre-configured column structure and filter state inside the log table layout.

EmbedViewConfig

Section titled “EmbedViewConfig”

You can pass a custom view configuration parameter to enforce presentation layouts directly in the signed token:

interface EmbedViewConfig {
  columns?: string[];
  defaultFilter?: {
    search?: string;
    action?: string;
  };
}

Columns Configuration

Section titled “Columns Configuration”

The columns list controls which table columns are rendered in the embedded iframe. You can mix standard columns and dynamically pin metadata key paths:

  • Standard Columns: 'timestamp', 'actor', 'action', 'target', 'telemetry'.
  • Dynamic Metadata Pinning: Dotted paths matching fields in your JSON payloads (e.g. 'metadata.user_segment', 'metadata.account_type').

Example: columns: ['timestamp', 'actor', 'action', 'metadata.plan_tier']

Default Filters

Section titled “Default Filters”
  • search: A default text query to filter logs on (e.g. email, actor name, target, etc.).
  • action: An exact action event key filter.

EmbedTokenResult

Section titled “EmbedTokenResult”
Name Type Description
token string The raw HS256 JWT string.
embedUrl string Full embed URL: {dashboardUrl}/embed/{token}#{keyring} (hash fragment contains key ID and key values, e.g. v2:key2,v1:key1 or single legacy key).

JWT payload

Section titled “JWT payload”

The signed JWT contains:

Claim Description
pid Project ID
scope Query scope ('actor', 'target', 'tenant', or 'all')
abi Array of actor blind indexes computed against all keys in the keyring
tgb Array of target blind indexes computed against all keys in the keyring
tbi Array of tenant blind indexes computed against all keys in the keyring
iat Issued-at timestamp (Unix seconds)
exp Expiry timestamp (Unix seconds)
cols Compressed view columns config claim (signed if view.columns is defined)
flt Compressed view default filters claim (signed if view.defaultFilter is defined)

Example

Section titled “Example”
const { embedUrl } = await volidator.generateEmbedToken({
  actorId: session.userId,
  expiresIn: '2h',
  hostOrigin: 'https://app.example.com', // Required for secure JIT Hydration
  view: {
    columns: ['timestamp', 'actor', 'action', 'metadata.organization_id'],
    defaultFilter: {
      action: 'ORGANIZATION.MEMBER_PROMOTED'
    }
  }
});


// Pass embedUrl to the frontend for use in an <iframe src="">

Throws

Section titled “Throws”

generateEmbedToken() throws an Error if projectId or clientSecret are not set in the constructor.

Error: generateEmbedToken() requires projectId and clientSecret in the VolidatorClient constructor.
Section titled “Related”