Skip to main content

​
@ave-id/embed

The Ave embed library provides a lightweight, iframe-based solution for integrating Ave authentication into your web application. It uses postMessage callbacks for secure communication between your app and the Ave authentication flow.

​
Installation

npm install @ave-id/embed

​
Embedding Options

The library supports multiple embedding strategies to fit different use cases:

​
Inline iframe

Embed the authentication flow directly into your page using mountAveEmbed(). Best for:
  • Dedicated sign-in pages
  • Seamless user experience
  • Full control over positioning
Learn more about inline iframes Display authentication in a mobile-friendly bottom sheet using openAveSheet(). Best for:
  • Mobile-first applications
  • Native app-like experience
  • Overlay authentication flows
Learn more about modal sheets Open authentication in a separate popup window using openAvePopup(). Best for:
  • Desktop applications
  • Multi-window workflows
  • Traditional OAuth flows
Learn more about popup windows

​
Common Configuration

All embedding methods share common configuration options:
OptionTypeRequiredDefaultDescription
clientIdstringYes-Your Ave client ID
redirectUristringYes-OAuth redirect URI
scopestringNo"openid profile email"OAuth scopes
issuerstringNo"https://aveid.net"Ave issuer URL
onSuccessfunctionNo-Success callback with redirect URL
onErrorfunctionNo-Error callback with error details
onClosefunctionNo-Close callback (sheet/popup only)

​
Callbacks

​
onSuccess

Called when authentication completes successfully: 
onSuccess: ({ redirectUrl }) => {
  window.location.href = redirectUrl;
}

​
onError

Called when an error occurs during authentication: 
onError: (payload) => {
  console.error("Authentication error:", payload);
}

​
onClose

Called when the user closes the sheet or popup (not available for inline iframes): 
onClose: () => {
  console.log("User closed authentication");
}
All callbacks use postMessage for secure cross-origin communication between your app and the Ave authentication iframe.

​
Advanced Flows

For advanced use cases, the library also supports:
  • Connector flows - Separate resource authorization flows using openAveConnectorSheet()
  • Runtime execution - Protected browser execution with openAveConnectorRuntime()
Learn more about connector flows

​
Browser Compatibility

The embed library requires browsers that support:
  • iframes with allow attributes
  • postMessage API
  • ES6+ JavaScript features
Most modern browsers are supported, but IE11 and older browsers are not compatible.

​
Next Steps

Choose an embedding method that fits your use case:

Inline iframe

Embed authentication directly in your page

Modal sheet

Mobile-friendly bottom sheet overlay

Popup window

Traditional popup window flow

Connector flow

Advanced resource authorization

Build docs developers (and LLMs) love

Get started for freeTalk to us