@agentkeychain/web

Web SDK for AgentKeychain — a drop-in "Sign in with AgentKeychain" button and OIDC redirect flow for browser apps.

This package handles the browser side of the OIDC authorization-code flow with PKCE: generating a code verifier, kicking off the redirect to the authorize page, and parsing the callback. The token exchange step runs on your backend using @agentkeychain/server.

Installation

npm install @agentkeychain/web
# or
bun add @agentkeychain/web

react is an optional peer dependency — only install it if you use the React entry point.

Vanilla JS

Setup

import { AgentKeychainWeb } from "@agentkeychain/web";

const akc = new AgentKeychainWeb({
  clientId: "akc_client_...",
  redirectUri: "https://yourapp.com/auth/callback",
  scope: "openid profile",
  // endpoint defaults to https://api.agentkeychain.com
});

Kick off sign-in

document.getElementById("login")!.addEventListener("click", () => {
  akc.signIn(); // full-page redirect to the authorize page
});

signIn() generates a PKCE code_verifier, stores it in sessionStorage along with the CSRF state, then navigates the window to /v1/authorize. It never resolves — the page is gone.

Drop-in button

import { AgentKeychainWeb, renderButton } from "@agentkeychain/web";

const akc = new AgentKeychainWeb({ clientId, redirectUri });
renderButton(akc, document.getElementById("login-slot")!);

Handle the redirect callback

On your redirect_uri page:

import { AgentKeychainWeb, AgentKeychainWebError } from "@agentkeychain/web";

const akc = new AgentKeychainWeb({ clientId, redirectUri });

try {
  const { code, codeVerifier, redirectUri } = akc.handleRedirectCallback();
  // POST to your backend — the backend does the code exchange with client_secret
  await fetch("/auth/exchange", {
    method: "POST",
    body: JSON.stringify({ code, codeVerifier, redirectUri }),
  });
} catch (err) {
  if (err instanceof AgentKeychainWebError) {
    // err.code: STATE_MISMATCH | MISSING_PENDING_REQUEST | MISSING_CODE | AUTHORIZE_ERROR
  }
}

Your backend then calls @agentkeychain/server's AgentKeychain.exchangeCode({ code, redirect_uri, code_verifier }) to get the tokens.

React

import { AgentKeychainWeb } from "@agentkeychain/web";
import { AgentKeychainButton } from "@agentkeychain/web/react";

const akc = new AgentKeychainWeb({
  clientId: "akc_client_...",
  redirectUri: "https://yourapp.com/auth/callback",
});

export function LoginPage() {
  return (
    <AgentKeychainButton
      client={akc}
      scope="openid profile"
      onError={(err) => console.error(err)}
    />
  );
}

Pass children or label to customize the button text, className or style to restyle.

Why redirect and not popup?

This version uses full-page redirects for simplicity — no postMessage, no popup-blocker edge cases, no callback HTML to serve. If you need popup UX later, a signInWithPopup() API can be added as a second option without breaking the redirect flow.

License

Apache-2.0