Skip to main content

Direct-link mode

Direct-link mode produces a self-contained URL that opens the component in the user's browser without your shell needing to be on the page. The URL is single-use: when the SPA loads, it exchanges the session ID for a JWT against Kaunt's backend, and the original URL becomes unusable.

Use direct-link when:

  • The user shouldn't have to be inside your application to act on the component — for example a one-off review link emailed to a vendor.
  • You need to support clients that can't host an iframe (some CRMs, ticketing systems, or native mobile apps that open external links).

If the component will live inside your existing logged-in application, prefer iframe mode — it avoids the link-as-credential problem entirely.

Creating the session​

Same endpoint as iframe mode, with accessMode: "direct-link". allowedOrigins is not required (and not used) for direct-link sessions.

POST /v1/tenants/05ed0ffa-1bf5-4bd1-9970-df7a78a948fe/embedded-components/sessions
Authorization: Bearer <your-kaunt-api-key>
Content-Type: application/json

{
  "component": "documentai-feedback-agent",
  "accessMode": "direct-link",
  "expiresInSeconds": 3600,
  "data": {
    "documentId": "227aebd0-36a4-4d17-b96d-c5b5d071abd4",
    "userId": "external-reviewer-7"
  }
}

The response omits the token field; the URL is the credential:

{
  "sessionId": "fb0ccbbc-62bc-447f-a47e-02b490e25690",
  "token": null,
  "url": "https://components.kaunt.com/documentai-feedback-agent?sessionId=fb0ccbbc-62bc-447f-a47e-02b490e25690&mode=direct-link",
  "accessMode": "direct-link",
  "expiresAt": 1717160000
}

Single-use semantics​

When the SPA boots from a direct-link URL it calls Kaunt to exchange the session ID for a JWT. That exchange consumes the session: a second tab loading the same URL receives 410 Gone and shows a "this link has already been used" message.

After the exchange, the SPA also strips the sessionId query parameter from the URL via history.replaceState. The page is now bound to the in-memory JWT and reloading the page will land the user back on the consumed-link message.

This means a direct-link URL is as sensitive as a password until it's consumed:

  • Don't log it.
  • Don't render it into pages that might be cached, indexed, or screen-shared.
  • Don't deliver it over channels that retain history beyond what the user controls (e.g. shared inboxes).
  • Email and signed-in product UI are reasonable channels; public chat rooms are not.

Once the user has loaded the URL once, the link is harmless.

Choosing a lifetime​

expiresInSeconds controls how long the link remains redeemable. Pick the shortest lifetime that fits the user journey:

  • An immediate review handoff inside your product: a few minutes is plenty.
  • A "click this link in the next day to review" email: up to the per-mode maximum.

Once the link is consumed, the active session has its own server-side TTL independent of the link expiry.

Revoking active sessions​

Direct-link sessions can be revoked exactly like iframe sessions via DELETE /v1/tenants/{tenantId}/embedded-components/sessions/{sessionId}. Any open tab using that session will see a session-revoked error event and stop working.

Revoking a session before it has been consumed is also valid and will turn the original URL into a 410 on the next click.

Error events​

In direct-link mode the SPA cannot postMessage to a parent — it has none. Errors surface in the SPA's own UI as a full-page error state. The same machine-readable error codes used in iframe mode (session-unavailable, session-revoked, etc.) appear in the rendered message; see Error events for the list.