Developer Workflow

This guide walks through implementing the Agent Access Security Broker (AASB) pattern in your application using the Securix SDKs.

Workflow Overview

Instead of building a direct provider OAuth redirect, you use the Securix SDKs to broker the connection:

1. Auth Initiation → 2. Redirection → 3. Token Abstraction → 4. API Usage → 5. Brokered Proxying

Step 1: Auth Initiation

Use the @securix/core SDK on your backend (or the Next.js handler) to initiate an auth session.

import { Securix } from "@securix/core";

const { authUrl } = await Securix.auth.createSession({
  apiKey: "YOUR_DEV_API_KEY", // Optional if set in environment
  entityId: "user_unique_id",
  flow: "popup", // or "device"
  providers: {
    gmail: {
      scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
    },
  },
});

Step 2: User Redirection & Handshake

Redirect the user to the generated authUrl. If you're using @securix/client on the frontend, the SecurixButton handles this automatically, including the secure cryptographic handshake.

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

<SecurixButton
  entityId="user_123"
  providers={{
    gmail: { scopes: ["https://www.googleapis.com/auth/gmail.readonly"] },
  }}
>
  Connect Gmail
</SecurixButton>;

Step 3: Token Abstraction

Securix vaults the real provider token. Your application never receives or stores sensitive OAuth tokens from Google, Microsoft, or others.

Securix stores provider credentials privately and maps them to the securix-entity-id.
Your app only needs to know that the user has completed authorization. You can rely on webhook events or polling the session status.

Step 4: API Usage

To access the user's data, use any official provider SDK (like googleapis or dropbox) but override the base URL to point to the Securix provider-specific proxy:

import { google } from "googleapis";

const gmail = google.gmail({
  version: "v1",
  rootUrl: "https://gmail.api.securix.app", // Point to Securix Proxy
  headers: {
    "securix-api-key": process.env.SECURIX_API_KEY,
    "securix-entity-id": user.securixEntityId,
    "securix-agent-id": "gemini_vscode_1"
  },
});

Step 5: Brokered Proxying

When the SDK makes a request:

It hits the Securix Proxy.
Securix validates your securix-api-key, securix-agent-id and the securix-entity-id.
Securix retrieves the real provider token from the Vault.
Securix applies any Security Rules (e.g., redacting sensitive data).
Securix forwards the request to the official provider API.
The response is returned through Securix, audited and cleaned.

Complete Example

"use client";
// 1. Frontend - Connect with SecurixButton
import { SecurixButton } from "@securix/client";

export function ConnectComponent() {
  return (
    <SecurixButton
      entityId="user_123"
      providers={{
        gmail: { scopes: ["https://www.googleapis.com/auth/gmail.readonly"] },
      }}
      onResult={(success) => {
        if (success) console.log("Handshake complete.");
      }}
    >
      Connect Gmail
    </SecurixButton>
  );
}

// 2. Backend - API handler (Next.js)
// app/api/securix/[[...path]]/route.ts
import { toNextJsHandler } from "@securix/core";
export const { GET, POST } = toNextJsHandler;

// 3. Data access using proxy
import { google } from "googleapis";

export async function listEmails(entityId: string) {
  const gmail = google.gmail({
    version: "v1",
    rootUrl: "https://gmail.api.securix.app",
    headers: {
      "securix-api-key": process.env.SECURIX_API_KEY,
      "securix-entity-id": entityId,,
      "securix-agent-id": "gemini_vscode_1"
    },
  });

  const response = await gmail.users.messages.list({ userId: "me" });
  return response.data;
}