Widget Configuration

The Mandaitor widget system allows tenants to configure how the delegation UI appears and behaves for their end users. Configuration is managed through the MandaitorConfigClient in the SDK.

Prerequisites

• A Mandaitor tenant account
• A Cognito JWT token for authenticated config operations
• The @mandaitor/sdk package installed

Overview

Widget configuration controls:

• Identity Providers: Which authentication methods are available (Auth0, Okta, Entra ID, EUDI Wallet).
• Taxonomy Libraries: Which industry taxonomies are loaded for action selection.
• Branding: Colors, logos, fonts, and consent text.
• Approval Workflows: Whether mandates require manual approval.
• Webhooks: Event notifications for mandate lifecycle changes.

Using the Config Client

import { MandaitorConfigClient } from "@mandaitor/sdk";

const configClient = new MandaitorConfigClient(
  "https://api.mandaitor.io/v1",
  cognitoJwtToken,
  "tnt_your_tenant_id",
);

// Get current configuration
const config = await configClient.getWidgetConfig();
console.log(config.branding.primaryColor);

Updating Branding

await configClient.updateWidgetConfig({
  branding: {
    primaryColor: "#FF6B00",
    logoUrl: "https://example.com/logo.png",
    accentColor: "#333333",
    darkMode: false,
    borderRadius: "8px",
    consentText: {
      title: "Delegation Consent",
      description: "You are granting the following permissions...",
      locale: "en",
    },
  },
});

Configuring Taxonomy Libraries

Select which industry taxonomies are available in the mandate creation wizard:

await configClient.updateWidgetConfig({
  taxonomyLibraries: ["@mandaitor/taxonomy-construction", "@mandaitor/taxonomy-healthcare"],
});

Available official taxonomies:

• @mandaitor/taxonomy-construction — BIM validation, scheduling, procurement, cost management
• @mandaitor/taxonomy-healthcare — Clinical documentation, prescriptions, discharge, telemedicine
• @mandaitor/taxonomy-defence-isr — Intelligence analysis, sensor tasking, engagement authorization

Custom taxonomies with the @custom/ prefix are also supported for tenant-specific workflows.

Security Considerations

• Only taxonomies published in the Mandaitor taxonomy manifest (or @custom/ prefixed) are accepted
• Attempting to set an unknown taxonomy package will return a validation error
• The manifest is updated with each @mandaitor/taxonomy-* release

Configuring Approval Workflows

Enable mandatory approval for mandate creation:

await configClient.updateWidgetConfig({
  approvalWorkflow: {
    enabled: true,
    autoApproveRiskLevels: ["LOW", "MEDIUM"], // Only HIGH/CRITICAL need approval
    defaultApprover: "role:project-manager",
  },
});

When approval workflows are enabled, mandates created for HIGH or CRITICAL risk actions are automatically set to PENDING_APPROVAL state. See Creating Mandates — Approval Workflow for the SDK flow.

Public Widget Config (No Auth)

To fetch the public-safe widget configuration for embedding in a third-party site, no authentication is required:

const publicConfig = await configClient.getPublicWidgetConfig("wdg_abc123");
// Returns: widgetId, availableIdPs, taxonomyLibraries, branding, etc.
// Secrets and internal IDs are stripped from the response.

Validating IdP Connections

Test an Identity Provider configuration before saving:

const result = await configClient.validateIdPConfig("entra_id", {
  appRegistration: {
    tenantId: "your-azure-tenant-id",
    clientId: "your-client-id",
    clientSecretArn: "<your-secret-arn>",
  },
});

console.log(result.valid); // true or false
console.log(result.message); // "Entra ID credentials verified successfully"

Supported providers:

Provider	Key	Notes
Microsoft Entra ID	entra_id	Requires Azure app registration
Auth0	auth0	Domain + client ID + client secret
Okta	okta	Okta domain + client credentials
EUDI Wallet	eidas_eudi	EU Digital Identity Wallet (pilot phase)

Security Considerations

• Client secrets are stored securely and never exposed in the config response
• The clientSecretArn must be a valid ARN pointing to your stored secret
• Validation performs a live connection test — ensure network connectivity

Configuration Versioning

Every configuration update creates a new version. You can list previous versions and roll back if needed:

// List all versions
const versions = await configClient.listConfigVersions();
console.log(versions);
// [
//   { configVersion: 3, updatedAt: "2026-03-27T...", status: "active" },
//   { configVersion: 2, updatedAt: "2026-03-20T...", status: "archived" },
//   { configVersion: 1, updatedAt: "2026-03-15T...", status: "archived" },
// ]

// Rollback to a previous version
await configClient.rollbackConfig(1);
// Creates version 4 as a copy of version 1

Security Considerations

• Rollback creates a new version (it doesn't delete the current one)
• All version changes are recorded in the audit log
• Rolling back an IdP configuration may break authentication until secrets are re-validated

Webhooks

Configure webhook endpoints to receive event notifications:

await configClient.updateWidgetConfig({
  webhooks: [
    {
      url: "https://your-service.example.com/mandaitor-events",
      events: [
        "MANDATE_CREATED",
        "MANDATE_APPROVED",
        "MANDATE_REVOKED",
        "VERIFICATION_ALLOWED",
        "VERIFICATION_DENIED",
      ],
      secret: "<your-webhook-signing-secret>", // HMAC signing secret
    },
  ],
});

Webhook payloads include an X-Mandaitor-Signature header containing an HMAC-SHA256 signature for verification. Failed deliveries are retried with exponential backoff and sent to a dead-letter queue after exhaustion.