@ave-id/embed

bun add @ave-id/embed

The embed shows Ave’s sign-in inside your page. With onTokens, it generates PKCE, state, and nonce, exchanges the code, and returns the tokens together with any encryption keys from the callback fragment. The keys stay in the browser; only the authorization code and PKCE verifier are sent to the token endpoint.

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

await startAveAuth({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile offline_access e2ee:symmetric",
  onTokens: (tokens) => {
    // tokens.id_token, tokens.refresh_token, tokens.app_key
    createSession(tokens);
  },
  onError: ({ message }) => showError(message),
});

The embed checks state and nonce. Verify the id_token with verifyJwt from @ave-id/sdk, or on your server, before trusting its claims. Profile and email fields in tokens.user depend on the granted scopes. To persist tokens and keys, pass the response to AveSession:

onTokens: (tokens) => session.setTokensFromResponse(tokens),

Presentations

Function	Presentation	Returns
`startAveAuth(options)`	Sheet, or an inline iframe when `container` is set	Controls of the chosen presentation
`mountAveEmbed(options)`	Inline iframe in `container`	`{ iframe, destroy, postMessage }`
`openAveSheet(options)`	Modal sheet over the page	`{ iframe, close }`
`openAvePopup(options)`	Separate window	`{ popup, close }`, or `null` when blocked

All four return promises. Await them before using the returned controls.

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

const inline = await mountAveEmbed({
  container: document.getElementById("ave-embed")!,
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  onTokens: createSession,
});

inline.destroy();

const popup = await openAvePopup({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  onTokens: createSession,
  onError: ({ message }) => showError(message),
});

popup?.close();

Call these functions from a click handler. The popup is opened before PKCE preparation so the browser’s user activation is not lost. Sheets and inline embeds open a popup when Ave needs a full browser context; if that popup is blocked during an onTokens flow, onError receives popup_blocked, and the user can allow popups and try again.

Options

string

required

Your app’s client ID from devs.aveid.net.

string

required

A callback URL registered for your app. It must be identical during authorization and exchange.

string

default:"\"openid profile email\""

Space-separated scopes, including an encryption scope such as e2ee:symmetric or e2ee:asymmetric.

HTMLElement

Element for the inline iframe. Required by mountAveEmbed; makes startAveAuth render inline.

string

default:"\"https://aveid.net\""

Ave origin.

string

default:"\"dark\""

Sign-in theme.

number | string

Inline iframe dimensions, or popup window dimensions in pixels.

Record<string, string>

Extra sign-in parameters, such as { prompt: "select_account" } for a switch-account button.

(tokens: AveTokenResponse) => void

Receives the token response with merged encryption keys. Takes precedence over onSuccess.

({ redirectUrl }) => void

Receives the callback URL for an exchange your app performs itself.

({ error, message }) => void

Called when sign-in fails.

() => void

Called once when the user dismisses the flow. Completing or failing a flow does not also call it.

Handling the callback yourself

Provide onSuccess instead of onTokens when your app exchanges the code, for example on a server with a client secret. Public clients must generate and persist their own PKCE verifier, state, and nonce.

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

const verifier = generateCodeVerifier();
const state = generateNonce();
const nonce = generateNonce();
sessionStorage.setItem("ave_code_verifier", verifier);
sessionStorage.setItem("ave_state", state);
sessionStorage.setItem("ave_nonce", nonce);

await openAveSheet({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile e2ee:symmetric",
  codeChallenge: await generateCodeChallenge(verifier),
  codeChallengeMethod: "S256",
  extraParams: { state, nonce },
  onSuccess: ({ redirectUrl }) => window.location.assign(redirectUrl),
});

redirectUrl carries the encryption keys in its fragment. Navigating to it lets your callback page read them with mergeAppEncryptionFromUrl. If a sheet or inline embed needs a popup that the browser blocks, it redirects the current page to Ave instead, so persisted callback state must survive that navigation.

Security

Each embed accepts messages only from its configured Ave origin and from its own iframe or popup, so simultaneous flows stay separate. If you listen for message events yourself, check both event.origin and event.source.
Call destroy() or close() when your component unmounts to remove the frame and its listeners.
Do not load the embed inside a sandboxed iframe that blocks passkeys or popups.

JavaScript SDK

Embed SDK

@ave-id/embed

Presentations

Options

Handling the callback yourself

Security

​Presentations

​Options

​Handling the callback yourself

​Security

Presentations

Options

Handling the callback yourself

Security