Skip to main content

​
Inline iframe Embedding

The mountAveEmbed() function creates an inline iframe that embeds the Ave authentication flow directly into your page. This is ideal for dedicated sign-in pages where you want seamless integration.

​
Basic Usage

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

const { iframe } = mountAveEmbed({
  container: document.getElementById("ave-embed"),
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile email",
  onSuccess: ({ redirectUrl }) => {
    window.location.href = redirectUrl;
  },
  onError: (payload) => console.error("Embed error", payload),
});

​
HTML Setup

First, create a container element in your HTML: 
<div id="ave-embed"></div>
The iframe will be mounted inside this container.

​
Configuration Options

​
Required Options

OptionTypeDescription
containerHTMLElementDOM element where the iframe will be mounted
clientIdstringYour Ave client ID
redirectUristringOAuth redirect URI for your application

​
Optional Options

OptionTypeDefaultDescription
scopestring"openid profile email"OAuth scopes to request
issuerstring"https://aveid.net"Ave issuer URL
themestring-Theme customization
widthstring | number-iframe width (e.g., “100%” or 400)
heightstring | number-iframe height (e.g., “600px” or 600)
onSuccessfunction-Success callback
onErrorfunction-Error callback

​
Examples

​
Custom Dimensions

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

const { iframe } = mountAveEmbed({
  container: document.getElementById("ave-embed"),
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  width: "100%",
  height: 600,
  onSuccess: ({ redirectUrl }) => {
    window.location.href = redirectUrl;
  },
});

​
With Theme

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

const { iframe } = mountAveEmbed({
  container: document.getElementById("ave-embed"),
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  theme: "dark",
  onSuccess: ({ redirectUrl }) => {
    window.location.href = redirectUrl;
  },
});

​
React Integration

import { useEffect, useRef } from "react";
import { mountAveEmbed } from "@ave-id/embed";

function SignInPage() {
  const containerRef = useRef(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const { iframe } = mountAveEmbed({
      container: containerRef.current,
      clientId: process.env.REACT_APP_AVE_CLIENT_ID,
      redirectUri: `${window.location.origin}/callback`,
      scope: "openid profile email",
      onSuccess: ({ redirectUrl }) => {
        window.location.href = redirectUrl;
      },
      onError: (error) => {
        console.error("Authentication failed:", error);
      },
    });

    // Cleanup on unmount
    return () => {
      iframe?.remove();
    };
  }, []);

  return (
    <div>
      <h1>Sign in with Ave</h1>
      <div ref={containerRef} />
    </div>
  );
}

​
Vue Integration

<template>
  <div>
    <h1>Sign in with Ave</h1>
    <div ref="aveContainer"></div>
  </div>
</template>

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

export default {
  mounted() {
    mountAveEmbed({
      container: this.$refs.aveContainer,
      clientId: process.env.VUE_APP_AVE_CLIENT_ID,
      redirectUri: `${window.location.origin}/callback`,
      scope: "openid profile email",
      onSuccess: ({ redirectUrl }) => {
        window.location.href = redirectUrl;
      },
      onError: (error) => {
        console.error("Authentication failed:", error);
      },
    });
  },
};
</script>

​
Return Value

The mountAveEmbed() function returns an object with: 
{
  iframe: HTMLIFrameElement // The created iframe element
}
You can use the returned iframe reference for advanced manipulation if needed.

​
Callbacks

​
onSuccess

Called when the user successfully completes authentication: 
onSuccess: ({ redirectUrl }) => {
  // redirectUrl contains the OAuth callback URL with authorization code
  window.location.href = redirectUrl;
}

​
onError

Called when an error occurs during the authentication flow: 
onError: (payload) => {
  console.error("Authentication error:", payload);
  // Handle error (show message, retry, etc.)
}
Unlike openAveSheet() and openAvePopup(), inline iframes do not support the onClose callback since the iframe remains embedded in the page.

​
Security Considerations

Important security notes:
  • Always use HTTPS for your redirectUri in production
  • Validate the redirectUrl origin before redirecting to prevent open redirects
  • Store your clientId securely and avoid hardcoding sensitive values
  • The iframe uses postMessage for communication - ensure your CSP allows this

​
Styling

The iframe is created with minimal default styling. You can style the container element to control positioning: 
#ave-embed {
  max-width: 400px;
  margin: 0 auto;
  padding: 20px;
}

#ave-embed iframe {
  border: 1px solid #e5e7eb;
  border-radius: 8px;
}

​
Browser Compatibility

The inline iframe requires:
  • Modern browser with iframe support
  • postMessage API support
  • JavaScript enabled
All modern browsers (Chrome, Firefox, Safari, Edge) are fully supported.

​
Next Steps

Modal sheet

Use a mobile-friendly bottom sheet instead

Popup window

Open authentication in a popup window

Build docs developers (and LLMs) love

Get started for freeTalk to us