Authentication Flows

SecuriX provides two primary authentication flows designed to cover all application architectures while maintaining a Zero-Trust security model.

1. Popup Flow (Recommended for Web Apps)

The Popup Flow is designed for modern web applications where you want a seamless user experience. It uses a secure cryptographic handshake between your frontend and the SecuriX auth service.

How it works:

1. Backend Init: Your server (using the toNextJsHandler or @securix/core) creates an auth session.
2. Frontend Handshake: The SecurixButton from @securix/client generates a random secret (sxc) and opens the secure popup.
3. User Consent: The user authorizes the requested providers (Google, Dropbox, etc.) within the Securix UI.
4. Handshake Completion: The SecurixButton calls your backend to confirm the handshake using the sxc secret.
5. Webhook: Securix notifies your backend via webhook that the connection is ready.

// Frontend implementation
import { SecurixButton } from "@securix/client";

<SecurixButton
  entityId="user_123"
  providers={{
    gmail: { scopes: ["https://www.googleapis.com/auth/gmail.readonly"] }
  }}
  onResult={(success) => console.log("Auth result:", success)}
>
  Connect Securely
</SecurixButton>

Best for: React/Next.js apps, SPAs, and any application with a browser-based frontend.

2. Device Flow (Recommended for CLI & Servers)

The Device Flow is ideal for applications that don't have a traditional browser interface, such as CLI tools, IoT devices, or purely server-side scripts.

How it works:

1. Request Code: Your application calls SecuriX to request a device session.
2. Display Code: SecuriX returns an authUrl and a secure 8-character Device Code.
3. User Verification: You display the code to the user and ask them to visit the URL (on any device) to enter the code.
4. Remote Consent: Once the code is entered, the user authorizes the providers as usual.

// CLI / Backend implementation
import { Securix } from "@securix/sdk";

const { authUrl, deviceAuthCode } = await Securix.auth.createSession({
  entityId: "cli_user_1",
  flow: "device",
  providers: {
    gmail: { scopes: ["https://www.googleapis.com/auth/gmail.readonly"] }
  }
});

console.log(`🔗 Open: ${authUrl}`);
console.log(`🔑 Code: ${deviceAuthCode}`);

Best for: CLI tools (like securix-cli), terminal-based apps, and headless servers.

Comparing the Flows

Zero-Trust Architecture

Regardless of the flow you choose, SecuriX maintains a strict Zero-Trust policy:

• Raw Tokens Never Leave SecuriX: Your server never handles or stores raw OAuth tokens from Google, Microsoft, or others.
• Identified by Entity: You interact with user data using your securix-api-key, securix-agent-id and a unique securix-entity-id.
• Automatic Webhooks: Your backend is notified of events via secure webhooks, rather than handling sensitive redirect parameters.