Popup Flow Implementation

The Popup Flow is the standard way to connect users in a web application. Securix provides a pre-built React component, SecurixButton, which handles the secure cryptographic handshake (sxc) between your frontend, your backend, and the Securix Auth service.

1. Backend: Setup the Auth Handler

The SecurixButton expects two API endpoints on your server: one to create a session and one to confirm it. You can easily set these up using toNextJsHandler from @securix/core.

// app/api/securix/[[...path]]/route.ts
import { toNextJsHandler } from "@securix/core";

export const { GET, POST } = toNextJsHandler;

If you are not using Next.js, you can manually implement these endpoints by calling Securix.auth.createSession and Securix.auth.confirmSessionSXC.

2. Frontend: The SecurixButton

In your React/Next.js frontend, import and use the SecurixButton.

"use client";
import { SecurixButton } from "@securix/client";

const MyConnectButton = () => {
  return (
    <SecurixButton
      entityId="user_123"
      providers={{
        gmail: {
          scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
        },
        dropbox: {
          scopes: ["files.content.read"],
        },
      }}
      onResult={(success) => {
        if (success) {
          console.log("Authorization Successful!");
        }
      }}
    >
      Connect with Securix
    </SecurixButton>
  );
};

How it Works Under the Hood

1. Session Creation: The button calls your /api/securix/create-auth-session endpoint with a sxcHash.
2. Popup: A popup opens at auth.securix.app, where the user completes the OAuth flow.
3. Handshake: Once authorized, the popup sends a message back to the button.
4. Confirmation: The button calls your /api/securix/confirm-auth-session endpoint with the raw sxc to verify the handshake and finalize the connection.

3. Handling Webhooks (Optional)

While onResult provides immediate feedback, you should rely on Securix Webhooks for robust state management.

app.post("/api/webhooks/securix", (req, res) => {
  const { event, entityId } = req.body;

  if (event === "auth.completed") {
    console.log(`User ${entityId} has successfully connected their accounts.`);
    // You can now use the Securix Proxy to access their data
  }

  res.status(200).send("OK");
});

Next Steps