Files
skills/public/hanzo-id.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

325 lines
26 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hanzo-id</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hanzo-id.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hanzo-id">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hanzo-id.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hanzo-id</h1><p class="lede">Hanzo ID is the client-side identity story for every Hanzo/Lux/Zoo/Pars service: how an app authenticates a user against the shared IAM server and scopes data to the user&#x27;s org.</p><p>&lt;!-- Updated: 2026-07-23 --&gt;</p>
<h1>Hanzo ID - Client-Side Auth (OAuth2/OIDC via @hanzo/iam)</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Related Skills</strong>: <code>hanzo/hanzo-iam.md</code>, <code>hanzo/hanzo-platform.md</code>, <code>hanzo/hanzo-kms.md</code>, <code>hanzo/hanzo-cloud.md</code> <strong>Spec</strong>: HIP-0111 (auth) + HIP-0112 (cloud topology). Ground truth: <code>~/work/hanzo/CLAUDE.md</code>.</p>
<h2>Overview</h2>
<p>Hanzo ID is the <strong>client-side identity story</strong> for every Hanzo/Lux/Zoo/Pars service: how an app authenticates a user against the shared IAM server and scopes data to the user&#x27;s org. There is <strong>one and only one way</strong> to do it — the <strong><code>@hanzo/iam</code></strong> SDK against the canonical OIDC endpoints. This skill is the client contract. For the IAM <strong>server</strong> (Go backend, orgs, apps, admin API) see <code>hanzo/hanzo-iam.md</code>.</p>
<h2>The one way (non-negotiable)</h2>
<ul><li><strong>One package: <code>@hanzo/iam</code></strong> (npm, latest <strong>0.13.7</strong>). Framework-specific</li></ul>
<p> logic lives in subpaths — never re-implement any of it.</p>
<ul><li><strong>PKCE <code>S256</code> always.</strong> The default and only browser flow is OAuth2</li></ul>
<p> authorization-code + PKCE. No implicit flow. No ROPC (no password to the token endpoint).</p>
<ul><li><strong><code>client_secret_basic</code></strong> for confidential clients; <strong>scopes</strong></li></ul>
<p> <code>openid profile email</code>.</p>
<ul><li><strong><code>client_id = &lt;org&gt;-&lt;app&gt;</code></strong> (e.g. <code>hanzo-cloud</code>, <code>lux-console</code>,</li></ul>
<p> <code>zoo-cloud</code>). <code>redirectUris</code> must be the framework&#x27;s exact callback path.</p>
<ul><li><strong>Secrets in KMS.</strong> Superuser is <code>z@&lt;domain&gt;</code> / <code>Ilove&lt;App&gt;2026!!</code>.</li></ul>
<h3>Canonical endpoints (host-relative to the brand <code>serverUrl</code>)</h3>
<p>The SDK owns these in <code>src/paths.ts</code> (<code>OIDC_PATHS</code>) — the single source of truth. Every module resolves through it; no path string is written anywhere else.</p>
<p>| Purpose | Path | |---------|------| | OIDC discovery | <code>/.well-known/openid-configuration</code> | | Authorize | <code>/v1/iam/oauth/authorize</code> | | Token | <code>/v1/iam/oauth/token</code> | | UserInfo | <code>/v1/iam/oauth/userinfo</code> | | JWKS | <code>/v1/iam/.well-known/jwks</code> | | Logout (RP-initiated) | <code>/v1/iam/oauth/logout</code> |</p>
<h3>Brands (set <code>serverUrl</code> to the brand host)</h3>
<p>White-label is <strong>host-based</strong>: one IAM deployment serves every brand and selects the tenant by the origin it is reached on.</p>
<p>| Brand | <code>serverUrl</code> | |-------|-------------| | hanzo | <code>https://hanzo.id</code> | | lux | <code>https://lux.id</code> | | zoo | <code>https://zoolabs.id</code> (NOT <code>zoo.id</code>) | | pars | <code>https://pars.id</code> | | bootnode | <code>https://id.bootno.de</code> |</p>
<p><code>iam.hanzo.ai</code> is the <strong>internal backend/admin host</strong> — it is NOT the issuer and NOT a public <code>serverUrl</code>. The Hanzo-brand issuer is <strong><code>hanzo.id</code></strong>. Discovery is host-relative, so keep <code>originFrontend</code> EMPTY in the server&#x27;s <code>app.prod.conf</code> (see hanzo-iam.md).</p>
<h2>SDK subpaths (import the one that matches your runtime)</h2>
<p>| Subpath | Use | |---------|-----| | <code>@hanzo/iam/browser</code> | SPA PKCE: <code>configureIam</code>, <code>startLogin</code>, <code>handleCallback</code>, <code>getSession</code>, <code>getUser</code>, <code>logout</code>, <code>completePopupSignin</code>, <code>loginWithWallet</code> (SIWx). | | <code>@hanzo/iam/react</code> | React hooks/provider over the browser SDK. | | <code>@hanzo/iam/nextauth</code> | <code>IamProvider</code> for NextAuth. | | <code>@hanzo/iam/betterauth</code> | <code>iamProvider</code> for Better Auth — <strong>explicit endpoints</strong>, never <code>genericOAuth({discoveryUrl})</code>. | | <code>@hanzo/iam/passport</code> | Passport strategy (Node). | | <code>@hanzo/iam/server</code> | <code>validateToken</code>, <code>getServerSession</code> (verify bearer/JWTs server-side). | | <code>@hanzo/iam/express</code>, <code>@hanzo/iam/hono</code>, <code>@hanzo/iam/sveltekit</code>, <code>@hanzo/iam/remix</code> | Framework middleware adapters. | | <code>@hanzo/iam/validation</code> | Shared request/claim validation helpers. | | <code>@hanzo/iam/paths</code> | <code>OIDC_PATHS</code>, <code>serverUrlForBrand</code>, <code>iamUrl</code> — the endpoint SoT. |</p>
<h2>When to use</h2>
<ul><li>Adding auth to any Hanzo service (web, SPA, API, CLI, extension)</li><li>Configuring OAuth2/OIDC/PKCE login</li><li>Multi-org / white-label SSO</li><li>Extracting org from the JWT <code>owner</code> claim to scope data</li><li>Debugging login/token/callback issues</li></ul>
<h2>Quick reference</h2>
<p>| Item | Value | |------|-------| | SDK package | <code>@hanzo/iam</code> (npm, 0.13.7) | | Login/issuer (hanzo) | <code>https://hanzo.id</code> | | Internal API/admin host | <code>https://iam.hanzo.ai</code> (not the issuer) | | Flow | Authorization code + PKCE <code>S256</code> (only) | | Scopes | <code>openid profile email</code> | | <code>client_id</code> | <code>&lt;org&gt;-&lt;app&gt;</code> | | Token auth | <code>client_secret_basic</code> | | Login UI repo | <code>github.com/hanzoai/id</code> | | Server repo | <code>github.com/hanzoai/iam</code> (clean rewrite) | | K8s manifests | <code>universe/infra/k8s/iam/</code> |</p>
<h2>Browser SPA (PKCE) — the canonical flow</h2>
<pre><code class="lang-typescript">// One-time config (e.g. app bootstrap)
import { configureIam } from &quot;@hanzo/iam/browser&quot;
configureIam({
serverUrl: &quot;https://hanzo.id&quot;, // brand host (see table)
clientId: &quot;hanzo-cloud&quot;, // &lt;org&gt;-&lt;app&gt;
redirectUri: &quot;https://app.hanzo.ai/auth/callback&quot;, // exact registered URI
scope: &quot;openid profile email&quot;,
})</code></pre>
<pre><code class="lang-typescript">// Start login (button handler). PKCE S256 + state handled by the SDK.
import { startLogin } from &quot;@hanzo/iam/browser&quot;
await startLogin() // or startLogin({ provider: &quot;github&quot; })</code></pre>
<pre><code class="lang-typescript">// Callback route (/auth/callback). Exchange the single-use code ONCE.
import { handleCallback } from &quot;@hanzo/iam/browser&quot;
await handleCallback() // validates state, PKCE token exchange</code></pre>
<pre><code class="lang-typescript">// Reading identity anywhere after login
import { getUser, getSession, logout } from &quot;@hanzo/iam/browser&quot;
const user = await getUser() // { sub, email, owner, ... }</code></pre>
<p><code>getUser()</code> returns the OIDC userinfo shaped to camelCase. <code>owner</code> is the org slug — use it to scope data (see below). Social login (Google/GitHub) that must stay in-place uses <code>signinPopup()</code> + <code>completePopupSignin()</code> on the callback route; wallet login uses <code>loginWithWallet()</code> (inline SIWx / EIP-4361, no redirect). All paths converge on the SAME PKCE <code>handleCallback</code> exchange.</p>
<h2>PITFALL — single-use authorization code (guard the callback once)</h2>
<p>The authorization <code>code</code> is <strong>single-use</strong> and the PKCE <code>code_verifier</code> is <strong>removed before</strong> the token POST. If your callback effect runs twice — React 18 StrictMode double-invoke, a Fast-Refresh remount, or the user refreshing the callback URL — the second run has no verifier (or the server rejects the already-spent code), surfacing as &quot;Missing PKCE code verifier&quot; or a token exchange 400.</p>
<ul><li><code>handleCallback</code> is being made <strong>idempotent in v0.13.8+</strong> (a second call</li></ul>
<p> returns the already-exchanged session instead of throwing).</p>
<ul><li><strong>Consumers must still guard the callback effect to run exactly once</strong> — the</li></ul>
<p> code is single-use regardless of SDK version. Use a run-once ref/guard, not a bare <code>useEffect(fn, [])</code>:</p>
<pre><code class="lang-typescript">// ✅ Run-once callback effect
const ran = useRef(false)
useEffect(() =&gt; {
if (ran.current) return
ran.current = true
handleCallback().then(() =&gt; router.replace(&quot;/&quot;)).catch(showError)
}, [])</code></pre>
<p>Do NOT retrigger <code>handleCallback</code> on re-render, and do NOT navigate the user back onto the <code>?code=...</code> URL.</p>
<h2>Framework recipes</h2>
<h3>Next.js (NextAuth)</h3>
<pre><code class="lang-typescript">import NextAuth from &quot;next-auth&quot;
import { IamProvider } from &quot;@hanzo/iam/nextauth&quot;
export const { handlers, auth } = NextAuth({
providers: [
IamProvider({
serverUrl: &quot;https://hanzo.id&quot;,
clientId: process.env.IAM_CLIENT_ID!, // hanzo-&lt;app&gt;
clientSecret: process.env.IAM_CLIENT_SECRET!, // from KMS
}),
],
})</code></pre>
<h3>Better Auth</h3>
<pre><code class="lang-typescript">import { betterAuth } from &quot;better-auth&quot;
import { iamProvider } from &quot;@hanzo/iam/betterauth&quot;
export const auth = betterAuth({
// iamProvider wires the EXPLICIT /v1/iam/oauth/* endpoints.
// NEVER genericOAuth({ discoveryUrl }) — a wrong path returns IAM&#x27;s 200
// HTML SPA catch-all (silent breakage, not a 404).
plugins: [iamProvider({ serverUrl: &quot;https://hanzo.id&quot;, clientId, clientSecret })],
})</code></pre>
<h3>Server-side token validation</h3>
<pre><code class="lang-typescript">import { validateToken, getServerSession } from &quot;@hanzo/iam/server&quot;
const claims = await validateToken(bearer, { serverUrl: &quot;https://hanzo.id&quot; })
const orgId = claims.owner // &quot;hanzo&quot; | &quot;lux&quot; | &quot;zoo&quot; | &quot;pars&quot;</code></pre>
<h2>Org scoping (every authenticated service)</h2>
<p>Extract the org from the JWT <code>owner</code> claim and scope ALL queries to it.</p>
<pre><code class="lang-go">// Go service pattern (behind the gateway)
orgID := claims[&quot;owner&quot;].(string) // &quot;hanzo&quot;, &quot;lux&quot;, &quot;zoo&quot;, &quot;pars&quot;
db.Where(&quot;org_id = ?&quot;, orgID).Find(&amp;results)</code></pre>
<p>The gateway (<code>api.hanzo.ai</code>) validates the JWT and injects identity headers for downstream services (<code>X-Org-Id</code>, <code>X-User-Id</code>, <code>X-User-Email</code>), and <strong>strips any client-supplied</strong> identity headers first. Only the JWT-validated path sets them.</p>
<h2>Forbidden (one-way violations)</h2>
<p>| Never | Use instead | |-------|-------------| | <code>@hanzo/iam-js-sdk</code> (retired) | <code>@hanzo/iam</code> | | Hand-rolled OAuth (manual authorize-URL building, <code>response_type=token</code>) | <code>@hanzo/iam/browser</code> | | <code>genericOAuth({ discoveryUrl })</code> | <code>@hanzo/iam/betterauth</code> <code>iamProvider</code> (explicit endpoints) | | Legacy <code>/oauth/<em></code>, <code>/login/oauth/</em></code>, <code>/api/login/<em></code>, <code>/api/get-app-login</code>, <code>/api/get-account</code> | <code>/v1/iam/oauth/</em></code> + SDK <code>getUser()</code> | | Implicit flow | PKCE <code>S256</code> auth code | | <code>iam.hanzo.ai</code> as issuer/serverUrl | brand host (<code>hanzo.id</code>, …) | | Hardcoding <code>organization</code> in the login payload | <code>client_id = &lt;org&gt;-&lt;app&gt;</code> (org is derived) |</p>
<h2>Troubleshooting</h2>
<p>| Issue | Cause | Solution | |-------|-------|----------| | &quot;Missing PKCE code verifier&quot; | Callback effect ran twice / page refreshed on <code>?code=</code> | Guard the callback to run once (see pitfall); upgrade to <code>@hanzo/iam</code> 0.13.8+ | | Login returns a 200 HTML page, not JSON/tokens | Wrong path hit IAM&#x27;s SPA catch-all | Use canonical <code>/v1/iam/oauth/*</code>; never <code>genericOAuth({discoveryUrl})</code>; keep <code>originFrontend</code> empty | | Token exchange 400 on second attempt | Single-use code reused | Run <code>handleCallback</code> once; don&#x27;t re-navigate to the code URL | | Wrong org after login | Hardcoded <code>organization</code> | Use <code>client_id=&lt;org&gt;-&lt;app&gt;</code>; org comes from the app | | CORS failure on discovery | IAM omits ACAO | SDK falls back to the SAME canonical paths automatically; set <code>proxyBaseUrl</code> to keep token/userinfo same-origin via the gateway | | <code>zoo.id</code> returns nothing | Wrong host | Zoo&#x27;s IAM is <code>zoolabs.id</code> |</p>
<h2>Agent compatibility</h2>
<p>This skill is tool-agnostic markdown discoverable by both Claude (via <code>CLAUDE.md</code> → <code>LLM.md</code> and <code>INDEX.md</code>) and Codex (via <code>AGENTS.md</code> → <code>LLM.md</code>). Instructions are imperative and reference file paths, not any one agent.</p>
<h2>Related Skills</h2>
<ul><li><code>hanzo/hanzo-iam.md</code> — the IAM server (orgs, apps, admin API, ops)</li><li><code>hanzo/hanzo-identity.md</code> — DID / on-chain identity (distinct from OIDC auth)</li><li><code>hanzo/hanzo-platform.md</code> — PaaS (authenticates via <code>@hanzo/iam</code>)</li><li><code>hanzo/hanzo-kms.md</code> — where client secrets live</li><li><code>hanzo/hanzo-cloud.md</code> — cloud dashboard auth + billing</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2026-07-23 <strong>Category</strong>: Hanzo Ecosystem <strong>Related</strong>: auth, oauth2, oidc, pkce, iam, identity, sso, multi-org, @hanzo/iam <strong>Prerequisites</strong>: OAuth2/OIDC + PKCE concepts, JWT</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hanzo-id.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>