<iframe src="https://sandbox.etherfuse.com/auth/launch"></iframe>

<script>
  const origin = "https://sandbox.etherfuse.com";
  window.addEventListener("message", (event) => {
    if (event.origin !== origin) return;
    if (event.data?.type !== "etherfuse:auth:request") return;
    // event.source is the launch iframe — reply to it.
    event.source.postMessage(
      {
        type: "etherfuse:auth:response",
        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
        assertion: SIGNED_JWT,
        target: "/kyb",
      },
      origin,
    );
  });
</script>

User Authentication

Launch a user via postMessage

⚠️ Different host. Like POST /auth/launch, this lives on the app host (app.etherfuse.com / sandbox.etherfuse.com), not the API host. It is a browser-facing page, not a JSON API.

The postMessage variant of launch, for embedding the flow in an iframe or popup. Open /auth/launch with no body; on load it asks its embedder (your page) for credentials over postMessage, and you reply. Use this when you don’t want to server-render a form POST. It also lets you handle session expiration and launch into different targets seamlessly, without a redirect page.

postMessage contract

On load, the launch frame posts an etherfuse:auth:request message to its embedder.
Your page replies with an etherfuse:auth:response carrying the fields below.
If you need a moment to sign a JWT, send etherfuse:auth:await first so the frame doesn’t time out.

Fields

grant_type and assertion: a raw partner JWT (grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer) or a refresh_token from a prior server-side exchange (grant_type=refresh_token).
target: the app path to land on. Must be an allowed target; today /kyb, optionally with ?org=<org_id>. Any other path is rejected.
return_url (optional): where to send the user when they leave.

The JWT’s sub and scope follow the same rules as POST /auth/launch.

GET

auth

launch

<iframe src="https://sandbox.etherfuse.com/auth/launch"></iframe>

<script>
  const origin = "https://sandbox.etherfuse.com";
  window.addEventListener("message", (event) => {
    if (event.origin !== origin) return;
    if (event.data?.type !== "etherfuse:auth:request") return;
    // event.source is the launch iframe — reply to it.
    event.source.postMessage(
      {
        type: "etherfuse:auth:response",
        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
        assertion: SIGNED_JWT,
        target: "/kyb",
      },
      origin,
    );
  });
</script>

<iframe src="https://sandbox.etherfuse.com/auth/launch"></iframe>

<script>
  const origin = "https://sandbox.etherfuse.com";
  window.addEventListener("message", (event) => {
    if (event.origin !== origin) return;
    if (event.data?.type !== "etherfuse:auth:request") return;
    // event.source is the launch iframe — reply to it.
    event.source.postMessage(
      {
        type: "etherfuse:auth:response",
        grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
        assertion: SIGNED_JWT,
        target: "/kyb",
      },
      origin,
    );
  });
</script>

Response

200

An HTML page that requests credentials from the embedder over postMessage, establishes the session, and redirects the browser to target.

Launch a user into the app Exchange a partner JWT

⌘I