@ave-id/embed

bun add @ave-id/embed

The embed library provides inline, sheet, and popup presentations for Ave flows. It accepts callbacks only from its configured Ave origin and the iframe or popup belonging to that flow. For sign-in, startAveAuth, mountAveEmbed, openAveSheet, and openAvePopup return promises. Await the result before using its controls. Connector and signing helpers return their controls synchronously. Provide onTokens to handle PKCE, state, nonce, and the token exchange automatically. Granted encryption keys, previous keys, and the app_key_reset recovery flag are included from the callback fragment. Profile and email fields depend on the granted scopes.

import { startAveAuth } from "@ave-id/embed";

const auth = await startAveAuth({
  redirectUri: "https://yourapp.com/callback",
  onTokens: (tokens) => createSession(tokens),
  onError: ({ message }) => showError(message),
});

Omit clientId in startAveAuth to use Quick Ave for your callback origin. Supply onSuccess instead of onTokens for your own callback and code exchange. Public clients using onSuccess must persist their PKCE verifier, state, and nonce themselves.

UI patterns

Inline embed

Mount an iframe directly in a container element. Stays in page, no overlay. Good for dedicated auth pages.

Sheet

Slides up from the bottom as a fixed modal overlay. Good for triggering login from any page.

Popup

Opens a new browser window. Works well on desktop. Returns null if the browser blocks the popup.

Auth flows

`mountAveEmbed(options)`

Mounts an Ave auth iframe inside a container element. The iframe stays visible while the user completes login.

function mountAveEmbed(options: MountAveEmbedOptions): Promise<{
  iframe: HTMLIFrameElement;
  destroy: () => void;
  postMessage: (payload: unknown) => void;
}>

HTMLElement

required

The DOM element that will contain the iframe.

string

required

Your app’s client ID.

string

required

Registered redirect URI.

string

default:"\"openid profile email\""

Space-separated scopes.

(payload) => void

Called when the user completes login. payload.redirectUrl is the callback URL with the authorization code.

onSuccess: (payload) => {
  // Extract code from payload.redirectUrl and exchange it
  const url = new URL(payload.redirectUrl);
  const code = url.searchParams.get("code");
}

(payload) => void

Called on error. payload.error is the error string, payload.message is a human-readable description.

() => void

Called when the user closes the embed without completing auth.

import { mountAveEmbed } from "@ave-id/embed";

const { destroy } = await mountAveEmbed({
  container: document.getElementById("auth-container")!,
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile email",
  onSuccess: async ({ redirectUrl }) => {
    const code = new URL(redirectUrl).searchParams.get("code")!;
    const tokens = await exchangeCode({ clientId, redirectUri }, { code, codeVerifier });
    // Create your session
  },
  onError: ({ error, message }) => {
    console.error("Auth error:", error, message);
  },
  onClose: () => {
    console.log("User closed auth");
  },
});

// When done
destroy();

`openAveSheet(options)`

Opens a full-width sheet overlay from the bottom. Non-blocking — the user can dismiss it.

function openAveSheet(options: OpenAveSheetOptions): Promise<{
  close: () => void;
  iframe: HTMLIFrameElement;
}>

The sheet mounts to the document body and supports the same auth callbacks and PKCE options as the inline embed. When Ave requires a full browser context, the sheet opens a popup. If blocked, an onTokens flow reports popup_blocked so the app can invite the user to allow popups and retry. An application-managed onSuccess flow redirects the current page to Ave; persist callback state before opening it.

import { openAveSheet } from "@ave-id/embed";
import { generateCodeVerifier, generateCodeChallenge, exchangeCode } from "@ave-id/sdk";

async function loginWithSheet() {
  const verifier = generateCodeVerifier();
  const challenge = await generateCodeChallenge(verifier);

  const { close } = await openAveSheet({
    clientId: "YOUR_CLIENT_ID",
    redirectUri: "https://yourapp.com/callback",
    scope: "openid profile email",
    codeChallenge: challenge,
    codeChallengeMethod: "S256",
    onSuccess: async ({ redirectUrl }) => {
      close();
      const code = new URL(redirectUrl).searchParams.get("code")!;
      const tokens = await exchangeCode({ clientId, redirectUri }, { code, codeVerifier: verifier });
      // Create session
    },
    onError: ({ error }) => {
      close();
      showError(error);
    },
  });
}

`openAvePopup(options)`

Opens a popup window for Ave auth. Returns null if the browser blocked the popup — always handle that case.

function openAvePopup(options: OpenAvePopupOptions): Promise<{
  popup: Window;
  close: () => void;
} | null>

Additional options beyond sheet:

number

default:"450"

Popup window width in pixels.

number

default:"650"

Popup window height in pixels.

import { openAvePopup } from "@ave-id/embed";

const result = await openAvePopup({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  onSuccess: async ({ redirectUrl }) => {
    // Handle success
  },
});

if (!result) {
  // Popup was blocked — fall back to sheet or redirect
  openAveSheet(/* ... */);
}

Connector flows

`openAveConnectorSheet(options)` / `openAveConnectorPopup(options)`

Opens /connect for Connector consent in a sheet or popup. Both helpers return controls synchronously.

function openAveConnectorSheet(options: OpenAveConnectorOptions): {
  close: () => void;
  iframe: HTMLIFrameElement;
}

string

required

The target resource key.

string

The resource scope(s) to request.

string

default:"\"user_present\""

Communication mode: "user_present" or "background".

import { openAveConnectorSheet } from "@ave-id/embed";

const { close } = openAveConnectorSheet({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  resource: "target-resource-key",
  scope: "resource.read",
  mode: "user_present",
  onSuccess: async ({ redirectUrl }) => {
    close();
    // Exchange code for source token, then do token-exchange for delegated token
  },
  onError: ({ error }) => {
    close();
  },
});

`openAveConnectorRuntime(options)`

Mounts a Connector runtime iframe for active connector sessions where the source app communicates with the target resource UI.

function openAveConnectorRuntime(options: OpenAveConnectorRuntimeOptions): {
  iframe: HTMLIFrameElement;
  send: (payload: unknown) => void;
  destroy: () => void;
}

string

required

The delegated access token from the token-exchange grant.

HTMLElement

DOM element to mount the runtime iframe in.

() => void

Called when the runtime iframe is ready to receive messages.

(payload) => void

Called for events sent from the runtime iframe.

Signing flows

`openAveSigningSheet(options)`

Opens the signing UI as a sheet overlay and includes the embedding origin for result delivery.

function openAveSigningSheet(options: OpenAveSigningSheetOptions): {
  close: () => void;
  iframe: HTMLIFrameElement;
}

string

required

The signing request ID from createSignatureRequest.

(payload) => void

Called when the user approves and signs.

(payload) => void

Called when the user explicitly denies the request.

() => void

Called when the user closes the sheet without acting.

import { openAveSigningSheet } from "@ave-id/embed";
import { createSignatureRequest, verifySignature } from "@ave-id/sdk";

// 1. Create request on your server first
const { requestId } = await fetch("/api/signing/create", {
  method: "POST",
  body: JSON.stringify({ action: "approve_transfer" }),
}).then(r => r.json());

// 2. Present signing UI
const { close } = openAveSigningSheet({
  requestId,
  onSigned: async (payload) => {
    close();
    // Verify and execute the approved action server-side
    await fetch("/api/signing/confirm", {
      method: "POST",
      body: JSON.stringify({ requestId }),
    });
  },
  onDenied: () => {
    close();
    showMessage("Request was denied");
  },
  onClose: () => {
    close();
    showMessage("Request was cancelled");
  },
});

`openAveSigningPopup(options)`

Same as sheet but in a popup window.

function openAveSigningPopup(options: OpenAveSigningPopupOptions): {
  popup: Window;
  close: () => void;
} | null

Returns null if the popup was blocked. Fall back to sheet.

Security rules

Always validate postMessage event origins. Only trust events from your configured Ave issuer origin (https://aveid.net by default). The embed library handles this internally. If you listen for message events manually, validate both event.origin and event.source against the iframe or popup you opened.

Always call destroy() or close() when the component unmounts to remove event listeners and clean up iframes
Handle success, error, and dismissal. onClose fires once for dismissal; successful or failed completion does not also call it
Do not use popups as the primary UX on mobile — fall back to sheet
The embed does not work inside sandboxed iframes that restrict credentials or passkey access

JavaScript SDK

Embed SDK

@ave-id/embed

UI patterns

Inline embed

Sheet

Popup

Auth flows

`mountAveEmbed(options)`

`openAveSheet(options)`

`openAvePopup(options)`

Connector flows

`openAveConnectorSheet(options)` / `openAveConnectorPopup(options)`

`openAveConnectorRuntime(options)`

Signing flows

`openAveSigningSheet(options)`

`openAveSigningPopup(options)`

Security rules

​UI patterns

Inline embed

Sheet

Popup

​Auth flows

​mountAveEmbed(options)

​openAveSheet(options)

​openAvePopup(options)

​Connector flows

​openAveConnectorSheet(options) / openAveConnectorPopup(options)

​openAveConnectorRuntime(options)

​Signing flows

​openAveSigningSheet(options)

​openAveSigningPopup(options)

​Security rules

UI patterns

Auth flows

`mountAveEmbed(options)`

`openAveSheet(options)`

`openAvePopup(options)`

Connector flows

`openAveConnectorSheet(options)` / `openAveConnectorPopup(options)`

`openAveConnectorRuntime(options)`

Signing flows

`openAveSigningSheet(options)`

`openAveSigningPopup(options)`

Security rules