Authentication and security

API requests use the same bearer header for an Entra access token or an API key:

Credential	HTTP header
Entra access token	Authorization: Bearer <ENTRA_ACCESS_TOKEN>
API key	Authorization: Bearer <API_KEY>

Set TOKEN in the HTTP examples to either credential. Your application supplies the credential to Context provider at runtime through bearerToken or apiKey.

Credential placement

Configure the page API host before mounting and set the credential on the outer sea-context. Processes and individual widgets inherit its client.

Use the mounts in Application integration. Credentials are visible to JavaScript in the host page. Keep the host server's Azure credential on the server.

A non-empty bearerToken takes precedence over apiKey. An empty token permits API-key use where the deployment accepts keys. A rejected non-empty token reports an authentication error.

Pass the existing elements and a function from your application that returns a fresh token:

import { getWidgetConfig } from "@sea-dev/widget-lit/config";

async function readSubmission(context, submissionId, getFreshToken) {
  const read = () => {
    const { apiUrl } = getWidgetConfig();
    if (!apiUrl || apiUrl === "demo")
      throw new Error(
        "Configure the page API host before reading a submission.",
      );
    return fetch(`${apiUrl}/v2/submissions/${submissionId}/data`, {
      headers: { Authorization: `Bearer ${context.bearerToken}` },
    });
  };
  let response = await read();
  if (response.status === 401) {
    const token = await getFreshToken();
    context.bearerToken = token;
    await context.updateComplete;
    response = await read();
  }
  return response;
}

Providers inherit the page's API host or their enclosing context's connection. An explicit apiUrl selects another deployment. Nested providers inherit unset credentials. Set their credential when connecting to another deployment or using a different permitted identity.

Server authentication and access

Entra issues the access token. Request the API's Application ID URI followed by /.default using the host's configured Azure credential. The API validates issuer, audience, tenant and required role, then resolves the provisioned principal to an organisation member. A deployment configured with AUTH_REQUIRE_ENTRA=true accepts Entra tokens only.

The organisation credential permits API operations independently of the controls displayed by your application. Read-only widget settings control presentation. Actor identifiers provide correction attribution. A permission model is planned.

Browser storage

The credential stays in runtime element and client state. State ownership covers what else lives in browser memory or local storage. The examples keep their live connection values in memory until reload.

Network and content policy

The host browser calls the configured API origin and retrieves source documents from their signed URLs. Sea context records citation interactions through the API. PDF workers and spreadsheet WebAssembly load from the deployed application assets.

Merge these directives into the host's Content Security Policy, replacing the API and document origins with your deployment's origins:

connect-src 'self' https://YOUR_API_HOST https://YOUR_DOCUMENT_HOST blob:;
worker-src 'self' blob:;
script-src 'self' 'wasm-unsafe-eval';
style-src 'self' 'unsafe-inline';
img-src 'self' https://YOUR_DOCUMENT_HOST blob: data:;

blob: permits browser-generated document URLs and worker wrappers. WebAssembly compilation uses wasm-unsafe-eval. Lit component styles use style elements inside shadow roots; the policy shown permits those styles. Compatibility and deployment covers CORS and asset hosting.

The components execute with the host page's JavaScript privileges. Shadow roots scope component styles. Labels, filenames and extracted text use Lit text bindings.

When your application enforces Trusted Types, allow the lit-html policy.

Dependencies and licences

The package does not declare a license field. Use of the widget is covered by the customer's agreement with Sea.dev.

The widget uses Lit for rendering, PDF.js for PDF viewing and a WebAssembly spreadsheet parser. React wrappers use the host's React installation. Use focused imports to include the components your screen uses. Pin the supplied package archive and retain the consumer lockfile for dependency and licence review.

Dependency	Licence
Lit (lit, @lit/context, @lit-labs/virtualizer)	BSD-3-Clause
PDF.js (pdfjs-dist)	Apache-2.0
Spreadsheet parser (@dukelib/sheets-wasm)	MIT or Apache-2.0
Rules engine (@gorules/zen-engine-wasm)	MIT
JSZip	MIT or GPL-3.0-or-later
Zod	MIT

Authentication problems

Inspect an API request in the browser's Network panel. Confirm its origin and Authorization header. Error responses covers the codes behind a 401.