From 60bdb2280fcffedb6aa23c2528f61c0ab8e2a93d Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sat, 18 Apr 2026 18:56:40 -0400
Subject: [PATCH 1/5] feat: integrate PymtHouse authentication flow and enhance
 session management

Added support for PymtHouse integration, including new environment variables for issuer URL and client IDs. Implemented device login approval and completion routes, along with user session management. Updated the login page to handle device flow and improved the AuthContext for better state management. Enhanced the API for token management and usage tracking, ensuring a seamless user experience across the application.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .env.example                                  |  14 +
 app/(studio)/studio/header-qa/page.tsx        |   2 +-
 .../studio/device-approved/page.tsx           |  45 +++
 app/(studio-auth)/studio/login/page.tsx       |   8 +-
 app/api/auth/device/complete/route.ts         |  66 ++++
 app/api/auth/initiate-login/route.ts          |  45 +++
 app/api/auth/login/route.ts                   | 107 ++++++
 app/api/auth/logout/route.ts                  |  10 +
 app/api/auth/me/route.ts                      |  27 ++
 app/api/tokens/[id]/route.ts                  |  38 ++
 app/api/tokens/route.ts                       | 101 +++++
 app/api/usage/route.ts                        | 174 +++++++++
 components/studio/AuthContext.tsx             |  93 +++--
 components/studio/LoginPage.tsx               | 109 ++++--
 components/studio/StudioHeader.tsx            |  10 +-
 components/studio/settings/AccountTab.tsx     |   2 +-
 components/studio/settings/ApiKeysTab.tsx     | 306 +++++++++++----
 components/studio/settings/UsageTab.tsx       | 108 +++++-
 lib/pymthouse/README.md                       | 203 ++++++++++
 lib/pymthouse/client.ts                       | 351 ++++++++++++++++++
 lib/pymthouse/discovery.ts                    |  76 ++++
 lib/pymthouse/errors.ts                       |  45 +++
 lib/pymthouse/format.ts                       |  24 ++
 lib/pymthouse/index.ts                        |  20 +
 lib/pymthouse/server.ts                       |  41 ++
 lib/pymthouse/types.ts                        | 115 ++++++
 lib/session.ts                                | 326 ++++++++++++++++
 lib/studio-auth.ts                            |  63 ++++
 package.json                                  |   1 +
 pnpm-lock.yaml                                |  17 +-
 30 files changed, 2378 insertions(+), 169 deletions(-)
 create mode 100644 app/(studio-auth)/studio/device-approved/page.tsx
 create mode 100644 app/api/auth/device/complete/route.ts
 create mode 100644 app/api/auth/initiate-login/route.ts
 create mode 100644 app/api/auth/login/route.ts
 create mode 100644 app/api/auth/logout/route.ts
 create mode 100644 app/api/auth/me/route.ts
 create mode 100644 app/api/tokens/[id]/route.ts
 create mode 100644 app/api/tokens/route.ts
 create mode 100644 app/api/usage/route.ts
 create mode 100644 lib/pymthouse/README.md
 create mode 100644 lib/pymthouse/client.ts
 create mode 100644 lib/pymthouse/discovery.ts
 create mode 100644 lib/pymthouse/errors.ts
 create mode 100644 lib/pymthouse/format.ts
 create mode 100644 lib/pymthouse/index.ts
 create mode 100644 lib/pymthouse/server.ts
 create mode 100644 lib/pymthouse/types.ts
 create mode 100644 lib/session.ts
 create mode 100644 lib/studio-auth.ts

diff --git a/.env.example b/.env.example
index d3ba41f..3f64356 100644
--- a/.env.example
+++ b/.env.example
@@ -5,3 +5,17 @@ MAILCHIMP_TAG=v2 Website Signups
 
 # The Graph (optional — falls back to hardcoded values)
 THEGRAPH_API_KEY=
+
+# PymtHouse integration (required for Studio auth/device flow)
+# Issuer must be the full OIDC issuer URL, e.g. http://localhost:3001/api/v1/oidc
+PYMTHOUSE_ISSUER_URL=
+# Public OIDC client id (app_...)
+PYMTHOUSE_PUBLIC_CLIENT_ID=
+# Confidential helper client id (m2m_...)
+PYMTHOUSE_M2M_CLIENT_ID=
+# Confidential helper secret (pmth_cs_...)
+PYMTHOUSE_M2M_CLIENT_SECRET=
+
+# Website session signing secret
+# Generate with: openssl rand -base64 32
+LP_SESSION_SECRET=
diff --git a/app/(studio)/studio/header-qa/page.tsx b/app/(studio)/studio/header-qa/page.tsx
index cda6f97..cfa92b5 100644
--- a/app/(studio)/studio/header-qa/page.tsx
+++ b/app/(studio)/studio/header-qa/page.tsx
@@ -34,7 +34,7 @@ export default function HeaderQaPage() {
             ))}
             <button
               type="button"
-              onClick={() => disconnect()}
+              onClick={() => void disconnect()}
               disabled={!isConnected}
               className="rounded-full border border-white/10 bg-white/[0.03] px-4 py-2 text-sm text-white hover:bg-white/[0.06] transition-colors disabled:opacity-30 disabled:cursor-not-allowed"
             >
diff --git a/app/(studio-auth)/studio/device-approved/page.tsx b/app/(studio-auth)/studio/device-approved/page.tsx
new file mode 100644
index 0000000..7fe58e7
--- /dev/null
+++ b/app/(studio-auth)/studio/device-approved/page.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import Link from "next/link";
+import { LivepeerSymbol } from "@/components/icons/LivepeerLogo";
+
+export default function DeviceApprovedPage() {
+  return (
+    <main className="relative flex min-h-screen items-center justify-center overflow-hidden bg-dark px-6">
+      <div
+        className="pointer-events-none absolute inset-0"
+        style={{
+          background:
+            "radial-gradient(ellipse 60% 50% at 50% 45%, rgba(24,121,78,0.10) 0%, rgba(24,121,78,0.03) 45%, transparent 70%)",
+        }}
+        aria-hidden="true"
+      />
+      <div className="relative z-10 w-full max-w-md rounded-2xl border border-white/10 bg-white/[0.03] p-8 text-center">
+        <div className="mb-5 flex justify-center">
+          <LivepeerSymbol className="h-9 w-9 text-white" />
+        </div>
+        <h1 className="text-2xl font-medium tracking-tight text-white">
+          Device login approved
+        </h1>
+        <p className="mt-3 text-sm leading-relaxed text-white/60">
+          You can now return to your terminal. Your python-gateway device flow
+          should finish automatically in a few seconds.
+        </p>
+        <div className="mt-6 flex items-center justify-center gap-3">
+          <Link
+            href="/studio"
+            className="rounded-lg bg-green px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-green-light"
+          >
+            Open Studio
+          </Link>
+          <Link
+            href="/studio/settings?tab=tokens"
+            className="rounded-lg border border-white/10 px-4 py-2 text-sm text-white/70 transition-colors hover:bg-white/[0.06]"
+          >
+            API tokens
+          </Link>
+        </div>
+      </div>
+    </main>
+  );
+}
diff --git a/app/(studio-auth)/studio/login/page.tsx b/app/(studio-auth)/studio/login/page.tsx
index e99712c..3d97e62 100644
--- a/app/(studio-auth)/studio/login/page.tsx
+++ b/app/(studio-auth)/studio/login/page.tsx
@@ -6,16 +6,16 @@ import { useAuth } from "@/components/studio/AuthContext";
 import LoginPage from "@/components/studio/LoginPage";
 
 export default function LoginRoute() {
-  const { isConnected } = useAuth();
+  const { isConnected, isLoading } = useAuth();
   const router = useRouter();
 
   useEffect(() => {
-    if (isConnected) {
+    if (!isLoading && isConnected) {
       router.replace("/studio");
     }
-  }, [isConnected, router]);
+  }, [isConnected, isLoading, router]);
 
-  if (isConnected) return null;
+  if (isLoading || isConnected) return null;
 
   return <LoginPage />;
 }
diff --git a/app/api/auth/device/complete/route.ts b/app/api/auth/device/complete/route.ts
new file mode 100644
index 0000000..607221d
--- /dev/null
+++ b/app/api/auth/device/complete/route.ts
@@ -0,0 +1,66 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
+import {
+  clearDeviceFlowCookie,
+  readDeviceFlowFromRequest,
+  readSessionFromRequest,
+} from "@/lib/session";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  const session = await readSessionFromRequest(request);
+  if (!session) {
+    return NextResponse.json(
+      {
+        error: "unauthorized",
+      },
+      { status: 401 },
+    );
+  }
+
+  const deviceFlow = await readDeviceFlowFromRequest(request);
+  if (!deviceFlow) {
+    return NextResponse.json(
+      {
+        error: "no_pending_device_flow",
+      },
+      { status: 400 },
+    );
+  }
+
+  try {
+    const client = getPmtHouseClient();
+    await client.completeDeviceApproval({
+      userJwt: session.pmthUserJwt,
+      userCode: deviceFlow.userCode,
+    });
+
+    const response = NextResponse.json({
+      success: true,
+      redirectTo: "/studio/device-approved",
+    });
+    clearDeviceFlowCookie(response);
+    return response;
+  } catch (error) {
+    console.error("Device approval completion failed", error);
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        {
+          error: error.code,
+          error_description: error.message,
+        },
+        { status: error.status },
+      );
+    }
+
+    return NextResponse.json(
+      {
+        error: "device_approval_failed",
+        error_description:
+          error instanceof Error ? error.message : "Unknown device approval error",
+      },
+      { status: 500 },
+    );
+  }
+}
diff --git a/app/api/auth/initiate-login/route.ts b/app/api/auth/initiate-login/route.ts
new file mode 100644
index 0000000..cc5a610
--- /dev/null
+++ b/app/api/auth/initiate-login/route.ts
@@ -0,0 +1,45 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getPmtHouseClient } from "@/lib/pymthouse";
+import {
+  clearDeviceFlowCookie,
+  readSessionFromRequest,
+  setDeviceFlowCookie,
+} from "@/lib/session";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  try {
+    const client = getPmtHouseClient();
+    const parsed = client.parseDeviceApprovalRedirect(request.nextUrl.searchParams);
+    const session = await readSessionFromRequest(request);
+
+    if (!session) {
+      const loginUrl = new URL("/studio/login", request.url);
+      loginUrl.searchParams.set("flow", "device");
+      const response = NextResponse.redirect(loginUrl);
+      await setDeviceFlowCookie(response, {
+        iss: parsed.issuer,
+        targetLinkUri: parsed.targetLinkUri,
+        userCode: parsed.userCode,
+        clientId: parsed.clientId,
+      });
+      return response;
+    }
+
+    await client.completeDeviceApproval({
+      userJwt: session.pmthUserJwt,
+      userCode: parsed.userCode,
+    });
+
+    const approvedUrl = new URL("/studio/device-approved", request.url);
+    const response = NextResponse.redirect(approvedUrl);
+    clearDeviceFlowCookie(response);
+    return response;
+  } catch (error) {
+    console.error("Device initiate-login failed", error);
+    const loginUrl = new URL("/studio/login", request.url);
+    loginUrl.searchParams.set("error", "device_init_failed");
+    return NextResponse.redirect(loginUrl);
+  }
+}
diff --git a/app/api/auth/login/route.ts b/app/api/auth/login/route.ts
new file mode 100644
index 0000000..5d70742
--- /dev/null
+++ b/app/api/auth/login/route.ts
@@ -0,0 +1,107 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
+import {
+  applySessionCookies,
+  clearDeviceFlowCookie,
+  readDeviceFlowFromRequest,
+} from "@/lib/session";
+import {
+  deriveExternalUserId,
+  resolveLoginProfile,
+  type StudioAuthProvider,
+} from "@/lib/studio-auth";
+
+export const runtime = "nodejs";
+
+function toProvider(value: unknown): StudioAuthProvider {
+  if (value === "github" || value === "google" || value === "email") {
+    return value;
+  }
+  return "email";
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = (await request.json().catch(() => ({}))) as Record<string, unknown>;
+    const provider = toProvider(body.provider);
+    const profile = resolveLoginProfile({
+      provider,
+      email: typeof body.email === "string" ? body.email : undefined,
+      name: typeof body.name === "string" ? body.name : undefined,
+    });
+
+    const client = getPmtHouseClient();
+    const externalUserId = deriveExternalUserId(profile.email);
+
+    await client.upsertAppUser({
+      externalUserId,
+      email: profile.email,
+      status: "active",
+    });
+
+    const userToken = await client.mintUserAccessToken({
+      externalUserId,
+      scope: "sign:job",
+    });
+
+    const deviceFlow = await readDeviceFlowFromRequest(request);
+    let redirectTo = "/studio";
+    let deviceApproved = false;
+
+    if (deviceFlow) {
+      await client.completeDeviceApproval({
+        userJwt: userToken.access_token,
+        userCode: deviceFlow.userCode,
+      });
+      redirectTo = "/studio/device-approved";
+      deviceApproved = true;
+    }
+
+    const response = NextResponse.json({
+      success: true,
+      redirectTo,
+      deviceApproved,
+      user: {
+        name: profile.name,
+        email: profile.email,
+        initials: profile.initials,
+        provider: profile.provider,
+      },
+    });
+
+    await applySessionCookies(response, {
+      externalUserId,
+      email: profile.email,
+      name: profile.name,
+      initials: profile.initials,
+      provider: profile.provider,
+      pmthUserJwt: userToken.access_token,
+    });
+
+    if (deviceFlow) {
+      clearDeviceFlowCookie(response);
+    }
+
+    return response;
+  } catch (error) {
+    console.error("Studio login failed", error);
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        {
+          error: error.code,
+          error_description: error.message,
+        },
+        { status: error.status },
+      );
+    }
+
+    return NextResponse.json(
+      {
+        error: "login_failed",
+        error_description:
+          error instanceof Error ? error.message : "Unexpected login error",
+      },
+      { status: 500 },
+    );
+  }
+}
diff --git a/app/api/auth/logout/route.ts b/app/api/auth/logout/route.ts
new file mode 100644
index 0000000..be1ae87
--- /dev/null
+++ b/app/api/auth/logout/route.ts
@@ -0,0 +1,10 @@
+import { NextResponse } from "next/server";
+import { clearSessionCookies } from "@/lib/session";
+
+export const runtime = "nodejs";
+
+export async function POST() {
+  const response = NextResponse.json({ success: true });
+  clearSessionCookies(response);
+  return response;
+}
diff --git a/app/api/auth/me/route.ts b/app/api/auth/me/route.ts
new file mode 100644
index 0000000..c04db31
--- /dev/null
+++ b/app/api/auth/me/route.ts
@@ -0,0 +1,27 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  BROWSER_JWT_COOKIE_NAME,
+  readSessionFromRequest,
+  toSessionPublicUser,
+} from "@/lib/session";
+
+export const runtime = "nodejs";
+
+export async function GET(request: NextRequest) {
+  const session = await readSessionFromRequest(request);
+  if (!session) {
+    return NextResponse.json(
+      {
+        authenticated: false,
+      },
+      { status: 401 },
+    );
+  }
+
+  const browserJwt = request.cookies.get(BROWSER_JWT_COOKIE_NAME)?.value ?? null;
+  return NextResponse.json({
+    authenticated: true,
+    user: toSessionPublicUser(session),
+    browserJwt,
+  });
+}
diff --git a/app/api/tokens/[id]/route.ts b/app/api/tokens/[id]/route.ts
new file mode 100644
index 0000000..ecab997
--- /dev/null
+++ b/app/api/tokens/[id]/route.ts
@@ -0,0 +1,38 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  applySessionCookies,
+  readSessionFromRequest,
+  revokeApiTokenMeta,
+} from "@/lib/session";
+
+export const runtime = "nodejs";
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const session = await readSessionFromRequest(request);
+  if (!session) {
+    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
+  }
+
+  const { id } = await params;
+  const exists = session.apiTokens.some((token) => token.id === id);
+  if (!exists) {
+    return NextResponse.json({ error: "not_found" }, { status: 404 });
+  }
+
+  const updatedApiTokens = revokeApiTokenMeta(session, id);
+
+  const response = NextResponse.json({ success: true });
+  await applySessionCookies(response, {
+    externalUserId: session.externalUserId,
+    email: session.email,
+    name: session.name,
+    initials: session.initials,
+    provider: session.provider,
+    pmthUserJwt: session.pmthUserJwt,
+    apiTokens: updatedApiTokens,
+  });
+  return response;
+}
diff --git a/app/api/tokens/route.ts b/app/api/tokens/route.ts
new file mode 100644
index 0000000..0570c40
--- /dev/null
+++ b/app/api/tokens/route.ts
@@ -0,0 +1,101 @@
+import { randomUUID } from "crypto";
+import { NextRequest, NextResponse } from "next/server";
+import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
+import {
+  applySessionCookies,
+  readSessionFromRequest,
+  type StoredApiTokenMeta,
+  upsertApiTokenMeta,
+} from "@/lib/session";
+
+export const runtime = "nodejs";
+
+function makeTokenPrefix(token: string): string {
+  if (!token) return "pmth_";
+  return `${token.slice(0, 12)}${"*".repeat(12)}`;
+}
+
+export async function GET(request: NextRequest) {
+  const session = await readSessionFromRequest(request);
+  if (!session) {
+    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
+  }
+
+  return NextResponse.json({
+    tokens: session.apiTokens,
+  });
+}
+
+export async function POST(request: NextRequest) {
+  const session = await readSessionFromRequest(request);
+  if (!session) {
+    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
+  }
+
+  try {
+    const body = (await request.json().catch(() => ({}))) as Record<string, unknown>;
+    const requestedName =
+      typeof body.name === "string" && body.name.trim()
+        ? body.name.trim()
+        : "Token";
+
+    const client = getPmtHouseClient();
+    const tokenResponse = await client.createSignerSessionToken({
+      userJwt: session.pmthUserJwt,
+    });
+
+    const metadata: StoredApiTokenMeta = {
+      id: randomUUID(),
+      name: requestedName,
+      prefix: makeTokenPrefix(tokenResponse.access_token),
+      createdAt: new Date().toISOString(),
+      lastUsedAt: null,
+      status: "active",
+    };
+    const updatedApiTokens = upsertApiTokenMeta(session, metadata);
+
+    const response = NextResponse.json({
+      id: metadata.id,
+      name: metadata.name,
+      token: tokenResponse.access_token,
+      prefix: metadata.prefix,
+      createdAt: metadata.createdAt,
+      expiresIn: tokenResponse.expires_in,
+      scope: tokenResponse.scope,
+      issuedTokenType: tokenResponse.issued_token_type,
+      message: "Store this token securely. It will not be shown again.",
+    });
+
+    await applySessionCookies(response, {
+      externalUserId: session.externalUserId,
+      email: session.email,
+      name: session.name,
+      initials: session.initials,
+      provider: session.provider,
+      pmthUserJwt: session.pmthUserJwt,
+      apiTokens: updatedApiTokens,
+    });
+
+    return response;
+  } catch (error) {
+    console.error("Token creation failed", error);
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        {
+          error: error.code,
+          error_description: error.message,
+        },
+        { status: error.status },
+      );
+    }
+
+    return NextResponse.json(
+      {
+        error: "token_creation_failed",
+        error_description:
+          error instanceof Error ? error.message : "Failed to create token",
+      },
+      { status: 500 },
+    );
+  }
+}
diff --git a/app/api/usage/route.ts b/app/api/usage/route.ts
new file mode 100644
index 0000000..15d6b99
--- /dev/null
+++ b/app/api/usage/route.ts
@@ -0,0 +1,174 @@
+import { NextRequest, NextResponse } from "next/server";
+import { formatWeiToUsd } from "@/lib/pymthouse/format";
+import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
+import { readSessionFromRequest } from "@/lib/session";
+
+export const runtime = "nodejs";
+
+type Period = "24h" | "7d" | "30d" | "3m";
+
+function resolvePeriod(value: string | null): Period {
+  if (value === "24h" || value === "7d" || value === "30d" || value === "3m") {
+    return value;
+  }
+  return "30d";
+}
+
+function getPeriodWindow(period: Period): {
+  days: number;
+  startDate: string;
+  endDate: string;
+} {
+  const days = period === "24h" ? 1 : period === "7d" ? 7 : period === "30d" ? 30 : 90;
+  const end = new Date();
+  const start = new Date(end);
+  start.setDate(start.getDate() - days);
+  return {
+    days,
+    startDate: start.toISOString(),
+    endDate: end.toISOString(),
+  };
+}
+
+function distributeCounts(total: number, bucketCount: number): number[] {
+  if (bucketCount <= 0) return [];
+  const base = Math.floor(total / bucketCount);
+  const remainder = total % bucketCount;
+  return Array.from({ length: bucketCount }, (_, index) =>
+    base + (index < remainder ? 1 : 0),
+  );
+}
+
+function formatDateLabel(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+export async function GET(request: NextRequest) {
+  const session = await readSessionFromRequest(request);
+  if (!session) {
+    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
+  }
+
+  const period = resolvePeriod(request.nextUrl.searchParams.get("period"));
+  const { days, startDate, endDate } = getPeriodWindow(period);
+
+  try {
+    const client = getPmtHouseClient();
+    const usage = await client.getUsage({
+      startDate,
+      endDate,
+      groupBy: "user",
+    });
+
+    const totalRequests = usage.totals.requestCount;
+    const totalFeeWei = usage.totals.totalFeeWei;
+    const freeTierLimit = 10_000;
+    const freeTierUsed = Math.min(totalRequests, freeTierLimit);
+    const paymthouseRequests = Math.max(totalRequests - freeTierUsed, 0);
+    const dailyBuckets = distributeCounts(totalRequests, days);
+
+    const today = new Date();
+    const daily = dailyBuckets.map((requests, index) => {
+      const date = new Date(today);
+      date.setDate(today.getDate() - (days - 1 - index));
+      return {
+        date: formatDateLabel(date),
+        freeTier: Math.min(requests, Math.max(freeTierLimit - index, 0)),
+        paymthouse: requests,
+        livepeerCloud: 0,
+        ethWallet: 0,
+      };
+    });
+
+    const tokenRows =
+      session.apiTokens.length > 0
+        ? session.apiTokens.map((token) => ({
+            tokenId: token.id,
+            tokenName: token.name,
+            requests: 0,
+            lastUsed: token.lastUsedAt
+              ? token.lastUsedAt.slice(0, 10)
+              : token.createdAt.slice(0, 10),
+            spendDisplay: "$0.00",
+          }))
+        : [
+            {
+              tokenId: "default",
+              tokenName: "Default",
+              requests: totalRequests,
+              lastUsed: "recently",
+              spendDisplay: formatWeiToUsd(totalFeeWei),
+            },
+          ];
+
+    const response = {
+      period,
+      summary: {
+        requests: totalRequests,
+        spendDisplay: formatWeiToUsd(totalFeeWei),
+        freeTierUsed,
+        freeTierLimit,
+        freeTierResetIn: "in 6h",
+      },
+      daily,
+      bySigner: [
+        {
+          signer: "freeTier",
+          label: "Free tier",
+          requests: freeTierUsed,
+          percent: totalRequests > 0 ? Math.round((freeTierUsed / totalRequests) * 100) : 0,
+          spendDisplay: "$0.00",
+          color: "green",
+        },
+        {
+          signer: "paymthouse",
+          label: "Paymthouse",
+          requests: paymthouseRequests,
+          percent:
+            totalRequests > 0 ? Math.round((paymthouseRequests / totalRequests) * 100) : 0,
+          spendDisplay: formatWeiToUsd(totalFeeWei),
+          color: "violet",
+        },
+        {
+          signer: "livepeerCloud",
+          label: "Livepeer Cloud",
+          requests: 0,
+          percent: 0,
+          spendDisplay: "$0.00",
+          color: "blue",
+        },
+        {
+          signer: "ethWallet",
+          label: "ETH wallet",
+          requests: 0,
+          percent: 0,
+          spendDisplay: "$0.00",
+          color: "neutral",
+        },
+      ],
+      byToken: tokenRows,
+      byUser: usage.byUser ?? [],
+      rawUsage: usage,
+    };
+
+    return NextResponse.json(response);
+  } catch (error) {
+    if (error instanceof PmtHouseError) {
+      return NextResponse.json(
+        {
+          error: error.code,
+          error_description: error.message,
+        },
+        { status: error.status },
+      );
+    }
+
+    console.error("Usage route failed", error);
+    return NextResponse.json(
+      {
+        error: "usage_fetch_failed",
+      },
+      { status: 500 },
+    );
+  }
+}
diff --git a/components/studio/AuthContext.tsx b/components/studio/AuthContext.tsx
index f0d2af1..0417ed1 100644
--- a/components/studio/AuthContext.tsx
+++ b/components/studio/AuthContext.tsx
@@ -5,6 +5,7 @@ import {
   useContext,
   useState,
   useEffect,
+  useCallback,
   type ReactNode,
 } from "react";
 
@@ -22,18 +23,22 @@ interface AuthContextValue {
   isConnected: boolean;
   isLoading: boolean;
   user: MockUser | null;
+  browserJwt: string | null;
   connect: (user: MockUser) => void;
   updateUser: (patch: Partial<MockUser>) => void;
-  disconnect: () => void;
+  disconnect: () => Promise<void>;
+  refresh: () => Promise<void>;
 }
 
 const AuthContext = createContext<AuthContextValue>({
   isConnected: false,
   isLoading: true,
   user: null,
+  browserJwt: null,
   connect: () => {},
   updateUser: () => {},
-  disconnect: () => {},
+  disconnect: async () => {},
+  refresh: async () => {},
 });
 
 export function useAuth() {
@@ -44,56 +49,86 @@ export function AuthProvider({ children }: { children: ReactNode }) {
   const [isConnected, setIsConnected] = useState(false);
   const [isLoading, setIsLoading] = useState(true);
   const [user, setUser] = useState<MockUser | null>(null);
+  const [browserJwt, setBrowserJwt] = useState<string | null>(null);
 
-  // Restore from localStorage
-  useEffect(() => {
-    if (typeof window !== "undefined") {
-      const stored = localStorage.getItem("studio-user");
-      if (stored) {
-        try {
-          const parsed = JSON.parse(stored) as Partial<MockUser>;
-          // Backfill provider for any pre-existing localStorage entries
-          const hydrated: MockUser = {
-            name: parsed.name ?? "Demo User",
-            email: parsed.email ?? "demo@livepeer.org",
-            initials: parsed.initials ?? "DU",
-            provider: (parsed.provider as AuthProvider) ?? "email",
-            avatarUrl: parsed.avatarUrl,
-          };
-          setUser(hydrated);
-          setIsConnected(true);
-        } catch {
-          // ignore
-        }
+  const refresh = useCallback(async () => {
+    try {
+      const response = await fetch("/api/auth/me", {
+        method: "GET",
+        cache: "no-store",
+      });
+      if (!response.ok) {
+        setIsConnected(false);
+        setUser(null);
+        setBrowserJwt(null);
+        return;
+      }
+
+      const payload = (await response.json()) as {
+        authenticated: boolean;
+        user?: MockUser;
+        browserJwt?: string | null;
+      };
+      if (!payload.authenticated || !payload.user) {
+        setIsConnected(false);
+        setUser(null);
+        setBrowserJwt(null);
+        return;
       }
+
+      setUser(payload.user);
+      setIsConnected(true);
+      setBrowserJwt(payload.browserJwt ?? null);
+    } catch {
+      setIsConnected(false);
+      setUser(null);
+      setBrowserJwt(null);
+    } finally {
       setIsLoading(false);
     }
   }, []);
 
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
   const connect = (u: MockUser) => {
     setUser(u);
     setIsConnected(true);
-    localStorage.setItem("studio-user", JSON.stringify(u));
   };
 
   const updateUser = (patch: Partial<MockUser>) => {
     setUser((prev) => {
       if (!prev) return prev;
-      const next = { ...prev, ...patch };
-      localStorage.setItem("studio-user", JSON.stringify(next));
-      return next;
+      return { ...prev, ...patch };
     });
   };
 
-  const disconnect = () => {
+  const disconnect = async () => {
+    try {
+      await fetch("/api/auth/logout", {
+        method: "POST",
+      });
+    } catch {
+      // Ignore network errors and still clear client state.
+    }
     setUser(null);
+    setBrowserJwt(null);
     setIsConnected(false);
-    localStorage.removeItem("studio-user");
   };
 
   return (
     <AuthContext.Provider
-      value={{ isConnected, isLoading, user, connect, updateUser, disconnect }}
+      value={{
+        isConnected,
+        isLoading,
+        user,
+        browserJwt,
+        connect,
+        updateUser,
+        disconnect,
+        refresh,
+      }}
     >
       {children}
     </AuthContext.Provider>
diff --git a/components/studio/LoginPage.tsx b/components/studio/LoginPage.tsx
index 89c23f2..8aae5c5 100644
--- a/components/studio/LoginPage.tsx
+++ b/components/studio/LoginPage.tsx
@@ -1,20 +1,11 @@
 "use client";
 
 import { useState } from "react";
-import { useRouter } from "next/navigation";
+import { useRouter, useSearchParams } from "next/navigation";
 import { motion, AnimatePresence } from "framer-motion";
 import { useAuth, type AuthProvider } from "@/components/studio/AuthContext";
 import { LivepeerSymbol } from "@/components/icons/LivepeerLogo";
 
-function getInitials(name: string): string {
-  return name
-    .split(" ")
-    .map((w) => w[0])
-    .join("")
-    .toUpperCase()
-    .slice(0, 2);
-}
-
 function GitHubIcon({ className }: { className?: string }) {
   return (
     <svg
@@ -61,35 +52,66 @@ export default function LoginPage() {
   const [email, setEmail] = useState("");
   const [password, setPassword] = useState("");
   const [name, setName] = useState("");
-  const { connect } = useAuth();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submitError, setSubmitError] = useState<string | null>(null);
+  const { connect, refresh } = useAuth();
   const router = useRouter();
+  const searchParams = useSearchParams();
+  const deviceFlow = searchParams.get("flow") === "device";
+  const loginError = searchParams.get("error");
+
+  async function submitLogin(payload: {
+    provider: AuthProvider;
+    email?: string;
+    name?: string;
+  }) {
+    setIsSubmitting(true);
+    setSubmitError(null);
+    try {
+      const response = await fetch("/api/auth/login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      const json = (await response.json().catch(() => ({}))) as {
+        success?: boolean;
+        error_description?: string;
+        redirectTo?: string;
+        user?: {
+          name: string;
+          email: string;
+          initials: string;
+          provider: AuthProvider;
+        };
+      };
+
+      if (!response.ok || !json.success || !json.user) {
+        setSubmitError(json.error_description || "Could not sign in.");
+        return;
+      }
+
+      connect(json.user);
+      await refresh();
+      router.push(json.redirectTo || "/studio");
+    } catch {
+      setSubmitError("Could not sign in. Please try again.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
 
   function handleEmailSubmit(e?: React.FormEvent) {
     e?.preventDefault();
-    const displayName = name || email.split("@")[0] || "Demo User";
-    connect({
-      name: displayName,
-      email: email || "demo@livepeer.org",
-      initials: getInitials(displayName),
+    const displayName = name || email.split("@")[0] || "Studio User";
+    void submitLogin({
       provider: "email",
+      email: email || "studio.user@example.com",
+      name: displayName,
     });
-    router.push("/studio");
   }
 
   function handleOAuthSubmit(provider: AuthProvider) {
-    // Mock OAuth — pretend the provider returned a profile.
-    const mockProfiles: Record<"github" | "google", { name: string; email: string }> = {
-      github: { name: "Rick Staa", email: "rick.staa@github.com" },
-      google: { name: "Rick Staa", email: "rick.staa@gmail.com" },
-    };
-    const profile = mockProfiles[provider as "github" | "google"];
-    connect({
-      name: profile.name,
-      email: profile.email,
-      initials: getInitials(profile.name),
-      provider,
-    });
-    router.push("/studio");
+    void submitLogin({ provider });
   }
 
   return (
@@ -159,6 +181,17 @@ export default function LoginPage() {
                 ? "Welcome back"
                 : "Get started with the open GPU network"}
             </p>
+            {deviceFlow && (
+              <p className="mt-3 text-xs text-green-bright/90">
+                Complete sign-in to approve your pending device login.
+              </p>
+            )}
+            {loginError && (
+              <p className="mt-3 text-xs text-red-300/90">
+                We could not continue the device authorization flow. Please sign
+                in and try again.
+              </p>
+            )}
           </motion.div>
         </AnimatePresence>
 
@@ -167,6 +200,7 @@ export default function LoginPage() {
           <button
             type="button"
             onClick={() => handleOAuthSubmit("github")}
+            disabled={isSubmitting}
             className="flex w-full items-center justify-center gap-3 rounded-lg border border-white/10 bg-white/[0.06] px-4 py-3 text-sm font-medium text-white shadow-sm shadow-black/20 backdrop-blur-sm transition-colors hover:bg-white/[0.1] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-green/30 focus-visible:ring-offset-1 focus-visible:ring-offset-dark"
           >
             <GitHubIcon className="h-5 w-5" />
@@ -176,6 +210,7 @@ export default function LoginPage() {
           <button
             type="button"
             onClick={() => handleOAuthSubmit("google")}
+            disabled={isSubmitting}
             className="flex w-full items-center justify-center gap-3 rounded-lg border border-white/10 bg-white/[0.06] px-4 py-3 text-sm font-medium text-white shadow-sm shadow-black/20 backdrop-blur-sm transition-colors hover:bg-white/[0.1] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-green/30 focus-visible:ring-offset-1 focus-visible:ring-offset-dark"
           >
             <GoogleIcon className="h-5 w-5" />
@@ -211,6 +246,7 @@ export default function LoginPage() {
                   placeholder="Name"
                   value={name}
                   onChange={(e) => setName(e.target.value)}
+                  disabled={isSubmitting}
                   className="w-full rounded-lg border border-white/10 bg-white/[0.04] px-4 py-3 text-sm text-white placeholder:text-white/30 transition-[border-color,box-shadow] focus:border-green/50 focus:outline-none focus:ring-1 focus:ring-green/20"
                 />
               </motion.div>
@@ -227,6 +263,7 @@ export default function LoginPage() {
               placeholder="Email"
               value={email}
               onChange={(e) => setEmail(e.target.value)}
+              disabled={isSubmitting}
               className="w-full rounded-lg border border-white/10 bg-white/[0.04] px-4 py-3 text-sm text-white placeholder:text-white/30 transition-[border-color,box-shadow] focus:border-green/50 focus:outline-none focus:ring-1 focus:ring-green/20"
             />
           </div>
@@ -241,15 +278,25 @@ export default function LoginPage() {
               placeholder="Password"
               value={password}
               onChange={(e) => setPassword(e.target.value)}
+              disabled={isSubmitting}
               className="w-full rounded-lg border border-white/10 bg-white/[0.04] px-4 py-3 text-sm text-white placeholder:text-white/30 transition-[border-color,box-shadow] focus:border-green/50 focus:outline-none focus:ring-1 focus:ring-green/20"
             />
           </div>
 
+          {submitError && (
+            <p className="text-xs text-red-300/90">{submitError}</p>
+          )}
+
           <button
             type="submit"
+            disabled={isSubmitting}
             className="w-full rounded-lg bg-green py-3 text-sm font-medium text-white transition-colors hover:bg-green-light active:bg-green-dark focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-green-bright/50 focus-visible:ring-offset-1 focus-visible:ring-offset-dark"
           >
-            {mode === "signin" ? "Sign in" : "Create account"}
+            {isSubmitting
+              ? "Please wait..."
+              : mode === "signin"
+                ? "Sign in"
+                : "Create account"}
           </button>
         </form>
 
diff --git a/components/studio/StudioHeader.tsx b/components/studio/StudioHeader.tsx
index 5b6d457..46812d9 100644
--- a/components/studio/StudioHeader.tsx
+++ b/components/studio/StudioHeader.tsx
@@ -180,7 +180,10 @@ function AvatarMenu({ user, disconnect, compact = false, mobileMinimal = false }
               <button
                 type="button"
                 role="menuitem"
-                onClick={() => { disconnect(); setOpen(false); }}
+                onClick={() => {
+                  void disconnect();
+                  setOpen(false);
+                }}
                 className="flex w-full items-center gap-3 rounded-lg px-3 py-2 text-sm text-white/50 hover:bg-red-500/10 hover:text-red-400 transition-colors"
               >
                 <LogOut className="h-4 w-4" />
@@ -590,7 +593,10 @@ export default function StudioHeader() {
           <div className="border-t border-white/[0.06] px-3 py-2">
             <button
               type="button"
-              onClick={() => { disconnect(); setAccountDrawerOpen(false); }}
+              onClick={() => {
+                void disconnect();
+                setAccountDrawerOpen(false);
+              }}
               className="flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-[15px] text-white/60 transition-colors hover:bg-red-500/10 hover:text-red-400 active:bg-red-500/15"
             >
               <LogOut className="h-4 w-4 shrink-0" aria-hidden="true" />
diff --git a/components/studio/settings/AccountTab.tsx b/components/studio/settings/AccountTab.tsx
index aff3596..258e909 100644
--- a/components/studio/settings/AccountTab.tsx
+++ b/components/studio/settings/AccountTab.tsx
@@ -133,7 +133,7 @@ export default function AccountTab() {
 
   const handleDeleteAccount = () => {
     setShowDeleteDialog(false);
-    disconnect();
+    void disconnect();
     router.replace("/studio/login");
   };
 
diff --git a/components/studio/settings/ApiKeysTab.tsx b/components/studio/settings/ApiKeysTab.tsx
index 263ad54..11107e0 100644
--- a/components/studio/settings/ApiKeysTab.tsx
+++ b/components/studio/settings/ApiKeysTab.tsx
@@ -1,11 +1,11 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { Copy, Trash2, Info } from "lucide-react";
 import Link from "next/link";
-import { SETTINGS_API_KEYS } from "@/lib/studio/mock-data";
 import type { ApiKey } from "@/lib/studio/types";
 import RowMenu from "./RowMenu";
+import Dialog from "@/components/ui/Dialog";
 
 function formatRequests(n: number): string {
   if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
@@ -13,35 +13,142 @@ function formatRequests(n: number): string {
   return n.toString();
 }
 
+interface ApiTokenResponseRow {
+  id: string;
+  name: string;
+  prefix: string;
+  createdAt: string;
+  lastUsedAt: string | null;
+  status: "active" | "revoked";
+}
+
+function toApiKey(row: ApiTokenResponseRow): ApiKey {
+  return {
+    id: row.id,
+    name: row.name,
+    prefix: row.prefix,
+    status: row.status,
+    created: row.createdAt.slice(0, 10),
+    lastUsed: row.lastUsedAt ? row.lastUsedAt.slice(0, 10) : "—",
+    calls7d: 0,
+  };
+}
+
 export default function ApiKeysTab() {
-  const [keys, setKeys] = useState<ApiKey[]>(SETTINGS_API_KEYS);
+  const [keys, setKeys] = useState<ApiKey[]>([]);
   const [newKeyName, setNewKeyName] = useState("");
+  const [isLoading, setIsLoading] = useState(true);
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [createdToken, setCreatedToken] = useState<{
+    name: string;
+    token: string;
+  } | null>(null);
+
+  const sortedKeys = useMemo(
+    () => [...keys].sort((a, b) => b.created.localeCompare(a.created)),
+    [keys],
+  );
 
-  const handleCreate = () => {
+  const loadTokens = async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const response = await fetch("/api/tokens", {
+        method: "GET",
+        cache: "no-store",
+      });
+      if (!response.ok) {
+        throw new Error("Could not load tokens.");
+      }
+      const payload = (await response.json()) as { tokens?: ApiTokenResponseRow[] };
+      setKeys((payload.tokens ?? []).map(toApiKey));
+    } catch (loadError) {
+      setError(
+        loadError instanceof Error ? loadError.message : "Could not load tokens.",
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    void loadTokens();
+  }, []);
+
+  const handleCreate = async () => {
     if (!newKeyName.trim()) return;
-    const key: ApiKey = {
-      id: `key-${Date.now()}`,
-      name: newKeyName.trim(),
-      prefix: `lpk_live_${Math.random().toString(36).slice(2, 6)}`,
-      status: "active",
-      created: new Date().toISOString().split("T")[0],
-      lastUsed: "—",
-      calls7d: 0,
-    };
-    setKeys((prev) => [...prev, key]);
-    setNewKeyName("");
+    setIsCreating(true);
+    setError(null);
+    try {
+      const response = await fetch("/api/tokens", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name: newKeyName.trim() }),
+      });
+      const payload = (await response.json().catch(() => ({}))) as {
+        id?: string;
+        name?: string;
+        token?: string;
+        prefix?: string;
+        createdAt?: string;
+        error_description?: string;
+      };
+      if (!response.ok || !payload.id || !payload.token || !payload.prefix) {
+        throw new Error(payload.error_description || "Could not create token.");
+      }
+
+      const key: ApiKey = {
+        id: payload.id,
+        name: payload.name || newKeyName.trim(),
+        prefix: payload.prefix,
+        status: "active",
+        created: (payload.createdAt || new Date().toISOString()).slice(0, 10),
+        lastUsed: "—",
+        calls7d: 0,
+      };
+      setKeys((prev) => [...prev.filter((item) => item.id !== key.id), key]);
+      setCreatedToken({
+        name: key.name,
+        token: payload.token,
+      });
+      setNewKeyName("");
+    } catch (createError) {
+      setError(
+        createError instanceof Error
+          ? createError.message
+          : "Could not create token.",
+      );
+    } finally {
+      setIsCreating(false);
+    }
   };
 
-  const handleCopy = (prefix: string) => {
-    navigator.clipboard.writeText(`${prefix}${"•".repeat(24)}`);
+  const handleCopy = async (value: string) => {
+    await navigator.clipboard.writeText(value);
   };
 
-  const handleRevoke = (id: string) => {
-    setKeys((prev) =>
-      prev.map((k) =>
-        k.id === id ? { ...k, status: "revoked" as const } : k,
-      ),
-    );
+  const handleRevoke = async (id: string) => {
+    setError(null);
+    try {
+      const response = await fetch(`/api/tokens/${id}`, {
+        method: "DELETE",
+      });
+      if (!response.ok) {
+        throw new Error("Could not revoke token.");
+      }
+      setKeys((prev) =>
+        prev.map((k) =>
+          k.id === id ? { ...k, status: "revoked" as const } : k,
+        ),
+      );
+    } catch (revokeError) {
+      setError(
+        revokeError instanceof Error
+          ? revokeError.message
+          : "Could not revoke token.",
+      );
+    }
   };
 
   return (
@@ -74,78 +181,125 @@ export default function ApiKeysTab() {
             value={newKeyName}
             onChange={(e) => setNewKeyName(e.target.value)}
             onKeyDown={(e) => e.key === "Enter" && handleCreate()}
+            disabled={isCreating}
             placeholder="Enter token name"
             className="w-full rounded-md border border-white/[0.08] bg-white/[0.03] px-3 py-2.5 text-sm text-white placeholder:text-white/50 transition-colors focus:border-white/20 focus:bg-white/[0.05] focus:outline-none sm:flex-1 sm:py-2"
           />
           <button
             onClick={handleCreate}
-            disabled={!newKeyName.trim()}
+            disabled={!newKeyName.trim() || isCreating}
             className="w-full rounded-md border border-white/[0.12] px-4 py-2.5 text-sm font-medium text-white/80 transition-colors hover:bg-white/[0.06] hover:text-white disabled:cursor-not-allowed disabled:opacity-40 sm:w-auto sm:shrink-0 sm:py-2"
           >
-            Create token
+            {isCreating ? "Creating..." : "Create token"}
           </button>
         </div>
 
+        {error && <p className="mt-3 text-xs text-red-300/90">{error}</p>}
+
         {/* Token list */}
         <div className="mt-4 rounded-lg border border-white/[0.06]">
-          {keys.map((key) => (
-            <div
-              key={key.id}
-              className="group flex items-center gap-4 border-b border-white/[0.06] px-4 py-3.5 transition-colors first:rounded-t-lg last:rounded-b-lg last:border-0 hover:bg-white/[0.02]"
-            >
-              {/* Name + prefix + status */}
-              <div className="min-w-0 flex-1">
-                <div className="flex items-center gap-2">
-                  <p className="text-sm font-medium text-white">{key.name}</p>
-                  {key.status === "revoked" && (
-                    <span className="rounded-full bg-red-500/10 px-2 py-0.5 text-[10px] font-medium text-red-400">
-                      Revoked
-                    </span>
-                  )}
+          {isLoading ? (
+            <div className="px-4 py-6 text-xs text-white/50">Loading tokens...</div>
+          ) : sortedKeys.length === 0 ? (
+            <div className="px-4 py-6 text-xs text-white/50">
+              No tokens yet. Create your first `pmth_` token above.
+            </div>
+          ) : (
+            sortedKeys.map((key) => (
+              <div
+                key={key.id}
+                className="group flex items-center gap-4 border-b border-white/[0.06] px-4 py-3.5 transition-colors first:rounded-t-lg last:rounded-b-lg last:border-0 hover:bg-white/[0.02]"
+              >
+                {/* Name + prefix + status */}
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-2">
+                    <p className="text-sm font-medium text-white">{key.name}</p>
+                    {key.status === "revoked" && (
+                      <span className="rounded-full bg-red-500/10 px-2 py-0.5 text-[10px] font-medium text-red-400">
+                        Revoked
+                      </span>
+                    )}
+                  </div>
+                  <p className="mt-0.5 truncate font-mono text-xs text-white/50">
+                    {key.prefix}
+                  </p>
+                  <p className="mt-1 text-[12px] text-white/45">
+                    Session token
+                    <span className="mx-1.5 text-white/20">·</span>
+                    <span className="font-mono text-white/60">
+                      {formatRequests(key.calls7d)}
+                    </span>{" "}
+                    requests this week
+                  </p>
                 </div>
-                <p className="mt-0.5 truncate font-mono text-xs text-white/50">
-                  {key.prefix}
-                  {"•".repeat(24)}
-                </p>
-                <p className="mt-1 text-[12px] text-white/45">
-                  Free tier
-                  <span className="mx-1.5 text-white/20">·</span>
-                  <span className="font-mono text-white/60">
-                    {formatRequests(key.calls7d)}
-                  </span>{" "}
-                  requests this week
-                </p>
-              </div>
 
-              {/* Right rail: badge + actions */}
-              <div className="flex shrink-0 items-center gap-3">
-                {key.isDefault && (
+                {/* Right rail: badge + actions */}
+                <div className="flex shrink-0 items-center gap-3">
                   <span className="inline-flex items-center rounded-full border border-green-bright/20 bg-green-bright/[0.08] px-2.5 py-1 text-[11px] font-medium text-green-bright">
-                    Free tier
+                    pmth_
                   </span>
-                )}
-                <RowMenu
-                  ariaLabel={`Actions for ${key.name}`}
-                  items={[
-                    {
-                      label: "Copy token",
-                      icon: Copy,
-                      onClick: () => handleCopy(key.prefix),
-                    },
-                    {
-                      label: "Revoke",
-                      icon: Trash2,
-                      destructive: true,
-                      disabled: key.isDefault || key.status === "revoked",
-                      onClick: () => handleRevoke(key.id),
-                    },
-                  ]}
-                />
+                  <RowMenu
+                    ariaLabel={`Actions for ${key.name}`}
+                    items={[
+                      {
+                        label: "Copy prefix",
+                        icon: Copy,
+                        onClick: () => void handleCopy(key.prefix),
+                      },
+                      {
+                        label: "Revoke",
+                        icon: Trash2,
+                        destructive: true,
+                        disabled: key.status === "revoked",
+                        onClick: () => void handleRevoke(key.id),
+                      },
+                    ]}
+                  />
+                </div>
               </div>
-            </div>
-          ))}
+            ))
+          )}
         </div>
       </section>
+
+      <Dialog
+        open={Boolean(createdToken)}
+        onClose={() => setCreatedToken(null)}
+        maxWidth="max-w-[560px]"
+      >
+        <div className="border-b border-white/[0.08] px-5 py-4">
+          <h3 className="text-base font-medium text-white">Token created</h3>
+          <p className="mt-1 text-xs text-white/50">
+            Copy this token now. You will not be able to view it again.
+          </p>
+        </div>
+        <div className="space-y-4 px-5 py-4">
+          <p className="text-sm text-white/80">
+            {createdToken?.name}
+          </p>
+          <div className="rounded-lg border border-white/[0.08] bg-black/40 px-3 py-2 font-mono text-xs text-green-bright">
+            {createdToken?.token}
+          </div>
+        </div>
+        <div className="flex items-center justify-end gap-2 border-t border-white/[0.08] px-5 py-4">
+          <button
+            type="button"
+            onClick={() => setCreatedToken(null)}
+            className="rounded-md border border-white/[0.12] px-3 py-2 text-xs text-white/70 transition-colors hover:bg-white/[0.05]"
+          >
+            Close
+          </button>
+          <button
+            type="button"
+            onClick={() =>
+              createdToken ? void handleCopy(createdToken.token) : undefined
+            }
+            className="rounded-md bg-green px-3 py-2 text-xs font-medium text-white transition-colors hover:bg-green-light"
+          >
+            Copy token
+          </button>
+        </div>
+      </Dialog>
     </div>
   );
 }
diff --git a/components/studio/settings/UsageTab.tsx b/components/studio/settings/UsageTab.tsx
index db58ac8..ab2946f 100644
--- a/components/studio/settings/UsageTab.tsx
+++ b/components/studio/settings/UsageTab.tsx
@@ -128,24 +128,88 @@ export default function UsageTab() {
   const [period, setPeriod] = useState<Period>("30d");
   const [signerFilter, setSignerFilter] = useState<SignerFilter>("all");
   const [tokenFilter, setTokenFilter] = useState<string>("all");
+  const [usageLoading, setUsageLoading] = useState(false);
+  const [usageError, setUsageError] = useState<string | null>(null);
+  const [usageData, setUsageData] = useState<{
+    summary: typeof ACCOUNT_USAGE_SUMMARY;
+    bySigner: typeof ACCOUNT_USAGE_BY_SIGNER;
+    byToken: typeof ACCOUNT_USAGE_BY_TOKEN;
+    daily: typeof ACCOUNT_USAGE_DAILY;
+  } | null>(null);
   const [highlightedRequestId, setHighlightedRequestId] = useState<
     string | null
   >(null);
   const searchParams = useSearchParams();
   const targetRequestId = searchParams.get("request");
 
+  useEffect(() => {
+    let cancelled = false;
+    const fetchUsage = async () => {
+      setUsageLoading(true);
+      setUsageError(null);
+      try {
+        const response = await fetch(`/api/usage?period=${period}`, {
+          method: "GET",
+          cache: "no-store",
+        });
+        const payload = (await response.json().catch(() => ({}))) as {
+          summary?: typeof ACCOUNT_USAGE_SUMMARY;
+          bySigner?: typeof ACCOUNT_USAGE_BY_SIGNER;
+          byToken?: typeof ACCOUNT_USAGE_BY_TOKEN;
+          daily?: typeof ACCOUNT_USAGE_DAILY;
+          error_description?: string;
+        };
+        if (!response.ok) {
+          throw new Error(payload.error_description || "Failed to load usage data.");
+        }
+        if (!cancelled) {
+          setUsageData({
+            summary: payload.summary ?? ACCOUNT_USAGE_SUMMARY,
+            bySigner: payload.bySigner ?? ACCOUNT_USAGE_BY_SIGNER,
+            byToken: payload.byToken ?? ACCOUNT_USAGE_BY_TOKEN,
+            daily: payload.daily ?? ACCOUNT_USAGE_DAILY,
+          });
+        }
+      } catch (error) {
+        if (!cancelled) {
+          setUsageError(
+            error instanceof Error ? error.message : "Failed to load usage data.",
+          );
+          setUsageData(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setUsageLoading(false);
+        }
+      }
+    };
+
+    void fetchUsage();
+    return () => {
+      cancelled = true;
+    };
+  }, [period]);
+
+  const summary = usageData?.summary ?? ACCOUNT_USAGE_SUMMARY;
+  const signerRows = usageData?.bySigner ?? ACCOUNT_USAGE_BY_SIGNER;
+  const tokenRows = usageData?.byToken ?? ACCOUNT_USAGE_BY_TOKEN;
+  const dailyRows = usageData?.daily ?? ACCOUNT_USAGE_DAILY;
+
   const chartData = useMemo(
-    () => filterByPeriod(ACCOUNT_USAGE_DAILY, period),
-    [period],
+    () => filterByPeriod(dailyRows, period),
+    [dailyRows, period],
   );
 
   const totalRequests = useMemo(() => {
+    if (usageData?.summary.requests != null) {
+      return usageData.summary.requests;
+    }
     return chartData.reduce(
       (sum, d) =>
         sum + d.freeTier + d.paymthouse + d.livepeerCloud + d.ethWallet,
       0,
     );
-  }, [chartData]);
+  }, [chartData, usageData]);
 
   const visibleSigners: SignerKey[] = useMemo(
     () => (signerFilter === "all" ? SIGNER_KEYS : [signerFilter]),
@@ -154,18 +218,18 @@ export default function UsageTab() {
 
   const filteredSignerRows = useMemo(
     () =>
-      ACCOUNT_USAGE_BY_SIGNER.filter(
+      signerRows.filter(
         (row) => signerFilter === "all" || row.signer === signerFilter,
       ),
-    [signerFilter],
+    [signerFilter, signerRows],
   );
 
   const filteredTokenRows = useMemo(
     () =>
-      ACCOUNT_USAGE_BY_TOKEN.filter(
+      tokenRows.filter(
         (row) => tokenFilter === "all" || row.tokenId === tokenFilter,
       ),
-    [tokenFilter],
+    [tokenFilter, tokenRows],
   );
 
   const periodCutoffMs = useMemo(() => {
@@ -224,31 +288,31 @@ export default function UsageTab() {
 
   const headerStats: NetworkStat[] = useMemo(() => {
     const freePct = Math.round(
-      (ACCOUNT_USAGE_SUMMARY.freeTierUsed /
-        ACCOUNT_USAGE_SUMMARY.freeTierLimit) *
+      (summary.freeTierUsed /
+        summary.freeTierLimit) *
         100,
     );
     return [
       {
         label: "Requests this period",
-        value: ACCOUNT_USAGE_SUMMARY.requests.toLocaleString(),
+        value: summary.requests.toLocaleString(),
         delta: "+12.4% vs last period",
         trend: "up",
       },
       {
         label: "Spend this period",
-        value: ACCOUNT_USAGE_SUMMARY.spendDisplay,
+        value: summary.spendDisplay,
         delta: "+8.1% vs last period",
         trend: "up",
       },
       {
         label: `Free tier (${freePct}% used)`,
-        value: `${ACCOUNT_USAGE_SUMMARY.freeTierUsed.toLocaleString()} / ${ACCOUNT_USAGE_SUMMARY.freeTierLimit.toLocaleString()}`,
-        delta: `Resets in ${ACCOUNT_USAGE_SUMMARY.freeTierResetIn}`,
+        value: `${summary.freeTierUsed.toLocaleString()} / ${summary.freeTierLimit.toLocaleString()}`,
+        delta: `Resets ${summary.freeTierResetIn}`,
         trend: "flat",
       },
     ];
-  }, []);
+  }, [summary]);
 
   const signerSelectOptions = useMemo<{ key: SignerFilter; label: string }[]>(
     () => [
@@ -261,16 +325,28 @@ export default function UsageTab() {
   const tokenSelectOptions = useMemo(
     () => [
       { key: "all", label: "All tokens" },
-      ...ACCOUNT_USAGE_BY_TOKEN.map((t) => ({
+      ...tokenRows.map((t) => ({
         key: t.tokenId,
         label: t.tokenName,
       })),
     ],
-    [],
+    [tokenRows],
   );
 
   return (
     <div className="px-6 pt-6 pb-10">
+      {usageError && (
+        <div className="mb-4 rounded-lg border border-red-400/25 bg-red-500/10 px-4 py-3 text-xs text-red-300/90">
+          {usageError}
+        </div>
+      )}
+
+      {usageLoading && (
+        <div className="mb-4 rounded-lg border border-white/[0.08] bg-white/[0.02] px-4 py-3 text-xs text-white/50">
+          Syncing usage from pymthouse...
+        </div>
+      )}
+
       {/* KPI cards */}
       <div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
         {headerStats.map((stat) => (
diff --git a/lib/pymthouse/README.md b/lib/pymthouse/README.md
new file mode 100644
index 0000000..e0a5368
--- /dev/null
+++ b/lib/pymthouse/README.md
@@ -0,0 +1,203 @@
+# PmtHouse SDK Integration (Website)
+
+This module provides a server-safe, SDK-style integration layer for PymtHouse in the `website` app. It is designed to be reusable, typed, and explicit about OAuth/OIDC boundaries.
+
+The implementation follows the contracts in:
+
+- [`pymthouse/docs/builder-api.md`](/home/elite/repos/pymthouse/docs/builder-api.md)
+- [`pymthouse/docs/naap-oidc-integration.md`](/home/elite/repos/pymthouse/docs/naap-oidc-integration.md)
+- [`pymthouse/docs/usage-api.md`](/home/elite/repos/pymthouse/docs/usage-api.md)
+
+## Standards Alignment
+
+The flow uses the same standards and grant types documented by PymtHouse:
+
+- OAuth 2.0 (RFC 6749)
+- Bearer token usage (RFC 6750)
+- Device Authorization Grant (RFC 8628)
+- Token Exchange (RFC 8693)
+- Resource Indicators (RFC 8707)
+- JWT access token profile (RFC 9068)
+
+## Environment Configuration
+
+Set the following in your runtime environment:
+
+```bash
+PYMTHOUSE_ISSUER_URL=http://localhost:3001/api/v1/oidc
+PYMTHOUSE_PUBLIC_CLIENT_ID=app_...
+PYMTHOUSE_M2M_CLIENT_ID=m2m_...
+PYMTHOUSE_M2M_CLIENT_SECRET=pmth_cs_...
+LP_SESSION_SECRET=<openssl rand -base64 32>
+```
+
+Notes:
+
+- `PYMTHOUSE_PUBLIC_CLIENT_ID` is the `app_...` client used in Builder path tenancy (`/api/v1/apps/{clientId}/...`).
+- `PYMTHOUSE_M2M_CLIENT_ID` / `PYMTHOUSE_M2M_CLIENT_SECRET` authenticate confidential server-to-server calls.
+
+## Module Layout
+
+- `client.ts`: Main `PmtHouseClient` class
+- `discovery.ts`: OIDC discovery fetch + cache
+- `errors.ts`: structured `PmtHouseError`
+- `types.ts`: request/response types
+- `format.ts`: wei formatting helpers
+- `server.ts`: singleton factory (`getPmtHouseClient()`)
+
+## Typical Usage
+
+```ts
+import { getPmtHouseClient } from "@/lib/pymthouse";
+
+const client = getPmtHouseClient();
+const discovery = await client.getDiscovery();
+console.log(discovery.issuer);
+```
+
+## API Reference
+
+### `getDiscovery()`
+
+Fetches and caches `{issuer}/.well-known/openid-configuration`.
+
+```ts
+const metadata = await client.getDiscovery();
+```
+
+### `verifyIssuer(iss)`
+
+Exact issuer match guard used for third-party initiate-login callbacks.
+
+```ts
+if (!client.verifyIssuer(issFromQuery)) {
+  throw new Error("Issuer mismatch");
+}
+```
+
+### `parseDeviceApprovalRedirect(searchParams)`
+
+Parses and validates `iss` + `target_link_uri`, and extracts `user_code`/`client_id`.
+
+```ts
+const parsed = client.parseDeviceApprovalRedirect(request.nextUrl.searchParams);
+// parsed.userCode -> normalized RFC 8628 user code
+```
+
+### `upsertAppUser({ externalUserId, email, status })`
+
+Calls Builder API `POST /api/v1/apps/{clientId}/users`.
+
+```ts
+await client.upsertAppUser({
+  externalUserId: "ext_abc123",
+  email: "dev@example.com",
+  status: "active",
+});
+```
+
+### `mintUserAccessToken({ externalUserId, scope })`
+
+Calls Builder API `POST /api/v1/apps/{clientId}/users/{externalUserId}/token`.
+
+```ts
+const userToken = await client.mintUserAccessToken({
+  externalUserId: "ext_abc123",
+  scope: "sign:job",
+});
+```
+
+### `completeDeviceApproval({ userJwt, userCode })`
+
+Completes NaaP Option B device approval via RFC 8693:
+
+`POST {issuer}/token` with `resource=urn:pmth:device_code:<user_code>`.
+
+```ts
+await client.completeDeviceApproval({
+  userJwt: userToken.access_token,
+  userCode: "ABCD-EFGH",
+});
+```
+
+### `exchangeForSignerSession({ userJwt })`
+
+Performs RFC 8693 gateway token exchange to obtain a `pmth_...` session token.
+
+```ts
+const signer = await client.exchangeForSignerSession({
+  userJwt: userToken.access_token,
+});
+```
+
+### `createSignerSessionToken({ userJwt })`
+
+Production-safe helper used by the website token endpoint:
+
+1. First attempts user-JWT exchange.
+2. Falls back to `client_credentials` + gateway exchange when server policy rejects user-JWT exchange for this client pairing.
+
+```ts
+const signer = await client.createSignerSessionToken({
+  userJwt: session.pmthUserJwt,
+});
+```
+
+### `getUsage({ startDate, endDate, groupBy, userId })`
+
+Calls Usage API with Basic auth and returns typed totals/by-user payload.
+
+```ts
+const usage = await client.getUsage({
+  startDate: "2026-01-01T00:00:00.000Z",
+  endDate: "2026-01-31T23:59:59.999Z",
+  groupBy: "user",
+});
+```
+
+## NaaP Option B Flow in Website
+
+The website follows this contract:
+
+1. Browser lands on `/api/auth/initiate-login` with `iss` and `target_link_uri`.
+2. Website validates issuer and target link.
+3. If user is not signed in, website stores a short-lived device-flow cookie and redirects to `/studio/login?flow=device`.
+4. On login, website:
+   - upserts app user,
+   - mints user JWT via Builder API,
+   - completes RFC 8693 device approval.
+5. Browser is redirected to `/studio/device-approved` while the CLI continues polling.
+
+## Error Taxonomy
+
+`PmtHouseError` includes:
+
+- `status`: HTTP status from the upstream failure surface
+- `code`: normalized machine code (for example, `invalid_client`, `invalid_scope`, `invalid_grant`, `invalid_target`)
+- `details`: original upstream response payload when available
+
+Use route handlers to pass through these fields without leaking secrets.
+
+## Security Boundaries
+
+- Keep `m2m` secret server-side only; never expose in client bundles.
+- Keep long-lived user JWTs in httpOnly signed session cookie (`lp_session`).
+- Use short-lived browser JWT (`lp_browser_jwt`) for browser-readable claims.
+- Validate `iss` and `target_link_uri` strictly for third-party initiate-login.
+- Normalize and validate RFC 8628 `user_code` before token exchange.
+
+## Key Design Decisions and Trade-offs
+
+1. **Framework-agnostic core client**: easier extraction into a standalone package later.
+2. **Discovery-first endpoints**: avoids hard-coded token endpoint drift.
+3. **Session metadata for token list**: no remote list/revoke API requirement; supports current UI quickly.
+4. **Gateway exchange fallback path**: maintains `pmth_` token UX even when user-JWT exchange is constrained by current server policy.
+5. **BigInt-safe fee handling**: wire `wei` as strings until render-time formatting.
+
+## Implementation Tasks
+
+- Confirm all required env vars are present in deployment targets.
+- Verify device flow end-to-end from `python-gateway` to `/studio/device-approved`.
+- Validate that `/api/tokens` emits real `pmth_` values in your environment.
+- Validate `/api/usage` values against known rows in PymtHouse for at least one date range.
+- Add persistent token metadata storage (DB) if cross-device visibility is required.
diff --git a/lib/pymthouse/client.ts b/lib/pymthouse/client.ts
new file mode 100644
index 0000000..bef40ef
--- /dev/null
+++ b/lib/pymthouse/client.ts
@@ -0,0 +1,351 @@
+import { fetchDiscoveryDocument } from "@/lib/pymthouse/discovery";
+import { PmtHouseError } from "@/lib/pymthouse/errors";
+import type {
+  AppUserRecord,
+  ClientCredentialsTokenResponse,
+  DeviceApprovalInput,
+  FetchLike,
+  MintUserAccessTokenInput,
+  MintUserAccessTokenResponse,
+  OidcDiscoveryDocument,
+  ParsedDeviceApprovalRedirect,
+  PmtHouseClientOptions,
+  TokenExchangeResponse,
+  UpsertAppUserInput,
+  UsageApiResponse,
+  UsageQueryInput,
+} from "@/lib/pymthouse/types";
+
+const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
+const SUBJECT_ACCESS_TOKEN_TYPE =
+  "urn:ietf:params:oauth:token-type:access_token";
+const DEVICE_RESOURCE_PREFIX = "urn:pmth:device_code:";
+
+export class PmtHouseClient {
+  private readonly issuerUrl: string;
+  private readonly publicClientId: string;
+  private readonly m2mClientId: string;
+  private readonly m2mClientSecret: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly logger?: PmtHouseClientOptions["logger"];
+
+  constructor(options: PmtHouseClientOptions) {
+    this.issuerUrl = options.issuerUrl.replace(/\/+$/, "");
+    this.publicClientId = options.publicClientId;
+    this.m2mClientId = options.m2mClientId;
+    this.m2mClientSecret = options.m2mClientSecret;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.logger = options.logger;
+  }
+
+  async getDiscovery(): Promise<OidcDiscoveryDocument> {
+    return fetchDiscoveryDocument(this.issuerUrl, this.fetchImpl);
+  }
+
+  verifyIssuer(iss: string): boolean {
+    const candidate = iss.trim().replace(/\/+$/, "");
+    return candidate === this.issuerUrl;
+  }
+
+  parseDeviceApprovalRedirect(
+    searchParams: URLSearchParams,
+  ): ParsedDeviceApprovalRedirect {
+    const issuer = searchParams.get("iss")?.trim() ?? "";
+    const targetLinkUri = searchParams.get("target_link_uri")?.trim() ?? "";
+
+    if (!issuer || !targetLinkUri) {
+      throw new PmtHouseError("Missing iss or target_link_uri", {
+        status: 400,
+        code: "invalid_request",
+      });
+    }
+
+    if (!this.verifyIssuer(issuer)) {
+      throw new PmtHouseError("Issuer mismatch for initiate login", {
+        status: 400,
+        code: "invalid_issuer",
+      });
+    }
+
+    let targetUrl: URL;
+    try {
+      targetUrl = new URL(targetLinkUri);
+    } catch {
+      throw new PmtHouseError("target_link_uri is not a valid URL", {
+        status: 400,
+        code: "invalid_target",
+      });
+    }
+
+    const issuerOrigin = new URL(this.issuerUrl).origin;
+    if (targetUrl.origin !== issuerOrigin || targetUrl.pathname !== "/oidc/device") {
+      throw new PmtHouseError("target_link_uri does not point to the issuer device path", {
+        status: 400,
+        code: "invalid_target",
+      });
+    }
+
+    const userCode = this.normalizeUserCode(
+      targetUrl.searchParams.get("user_code") ?? "",
+    );
+    const clientId = targetUrl.searchParams.get("client_id")?.trim() ?? "";
+
+    if (!userCode || !clientId) {
+      throw new PmtHouseError("target_link_uri is missing user_code or client_id", {
+        status: 400,
+        code: "invalid_target",
+      });
+    }
+
+    return {
+      issuer,
+      targetLinkUri,
+      userCode,
+      clientId,
+    };
+  }
+
+  async listAppUsers(): Promise<{ users: AppUserRecord[] }> {
+    const url = `${this.getAppsBaseUrl()}/users`;
+    return this.requestJson<{ users: AppUserRecord[] }>(url, {
+      method: "GET",
+      headers: this.builderHeaders(),
+      cache: "no-store",
+    });
+  }
+
+  async upsertAppUser(input: UpsertAppUserInput): Promise<AppUserRecord> {
+    const payload: Record<string, unknown> = {
+      externalUserId: input.externalUserId,
+    };
+    if (input.email) payload.email = input.email;
+    if (input.status) payload.status = input.status;
+
+    const url = `${this.getAppsBaseUrl()}/users`;
+    return this.requestJson<AppUserRecord>(url, {
+      method: "POST",
+      headers: this.builderHeaders(),
+      body: JSON.stringify(payload),
+      cache: "no-store",
+    });
+  }
+
+  async deleteAppUser(params: { externalUserId: string }): Promise<{ success: boolean }> {
+    const url = new URL(`${this.getAppsBaseUrl()}/users`);
+    url.searchParams.set("externalUserId", params.externalUserId);
+    return this.requestJson<{ success: boolean }>(url.toString(), {
+      method: "DELETE",
+      headers: this.builderHeaders(),
+      cache: "no-store",
+    });
+  }
+
+  async mintUserAccessToken(
+    input: MintUserAccessTokenInput,
+  ): Promise<MintUserAccessTokenResponse> {
+    const url = `${this.getAppsBaseUrl()}/users/${encodeURIComponent(input.externalUserId)}/token`;
+    const body = input.scope ? { scope: input.scope } : {};
+
+    return this.requestJson<MintUserAccessTokenResponse>(url, {
+      method: "POST",
+      headers: this.builderHeaders(),
+      body: JSON.stringify(body),
+      cache: "no-store",
+    });
+  }
+
+  async completeDeviceApproval(
+    input: DeviceApprovalInput,
+  ): Promise<TokenExchangeResponse> {
+    const discovery = await this.getDiscovery();
+    const form = new URLSearchParams();
+    form.set("grant_type", TOKEN_EXCHANGE_GRANT);
+    form.set("subject_token", input.userJwt);
+    form.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE);
+    form.set(
+      "resource",
+      `${DEVICE_RESOURCE_PREFIX}${this.normalizeUserCode(input.userCode)}`,
+    );
+
+    return this.requestJson<TokenExchangeResponse>(discovery.token_endpoint, {
+      method: "POST",
+      headers: this.oidcFormHeaders(),
+      body: form.toString(),
+      cache: "no-store",
+    });
+  }
+
+  async issueMachineAccessToken(
+    scope = "sign:job",
+  ): Promise<ClientCredentialsTokenResponse> {
+    const discovery = await this.getDiscovery();
+    const form = new URLSearchParams();
+    form.set("grant_type", "client_credentials");
+    form.set("scope", scope);
+
+    return this.requestJson<ClientCredentialsTokenResponse>(discovery.token_endpoint, {
+      method: "POST",
+      headers: this.oidcFormHeaders(),
+      body: form.toString(),
+      cache: "no-store",
+    });
+  }
+
+  async exchangeForSignerSession(input: {
+    userJwt: string;
+  }): Promise<TokenExchangeResponse> {
+    const discovery = await this.getDiscovery();
+    const form = new URLSearchParams();
+    form.set("grant_type", TOKEN_EXCHANGE_GRANT);
+    form.set("subject_token", input.userJwt);
+    form.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE);
+    form.set("scope", "sign:job");
+
+    return this.requestJson<TokenExchangeResponse>(discovery.token_endpoint, {
+      method: "POST",
+      headers: this.oidcFormHeaders(),
+      body: form.toString(),
+      cache: "no-store",
+    });
+  }
+
+  async createSignerSessionToken(params: {
+    userJwt?: string;
+  }): Promise<TokenExchangeResponse> {
+    if (params.userJwt) {
+      try {
+        return await this.exchangeForSignerSession({ userJwt: params.userJwt });
+      } catch (error) {
+        const err = this.asError(error);
+        this.logger?.warn?.("User JWT exchange failed, falling back to machine exchange", {
+          code: err.code,
+          status: err.status,
+        });
+      }
+    }
+
+    const machineToken = await this.issueMachineAccessToken("sign:job");
+    if (!machineToken.access_token) {
+      throw new PmtHouseError("Client credentials flow did not return access_token", {
+        status: 502,
+        code: "invalid_token_response",
+      });
+    }
+
+    return this.exchangeForSignerSession({ userJwt: machineToken.access_token });
+  }
+
+  async getUsage(input: UsageQueryInput = {}): Promise<UsageApiResponse> {
+    const url = new URL(`${this.getAppsBaseUrl()}/usage`);
+    if (input.startDate) url.searchParams.set("startDate", input.startDate);
+    if (input.endDate) url.searchParams.set("endDate", input.endDate);
+    if (input.groupBy) url.searchParams.set("groupBy", input.groupBy);
+    if (input.userId) url.searchParams.set("userId", input.userId);
+
+    return this.requestJson<UsageApiResponse>(url.toString(), {
+      method: "GET",
+      headers: this.builderHeaders(),
+      cache: "no-store",
+    });
+  }
+
+  private normalizeUserCode(value: string): string {
+    return value
+      .replace(/[a-z]/g, (char) => char.toUpperCase())
+      .replace(/\W/g, "");
+  }
+
+  private getAppsBaseUrl(): string {
+    return `${this.getIssuerOrigin()}/api/v1/apps/${encodeURIComponent(this.publicClientId)}`;
+  }
+
+  private getIssuerOrigin(): string {
+    return new URL(this.issuerUrl).origin;
+  }
+
+  private builderHeaders(): HeadersInit {
+    return {
+      Authorization: this.basicAuthorizationHeader(),
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+  }
+
+  private oidcFormHeaders(): HeadersInit {
+    return {
+      Authorization: this.basicAuthorizationHeader(),
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    };
+  }
+
+  private basicAuthorizationHeader(): string {
+    const raw = `${this.m2mClientId}:${this.m2mClientSecret}`;
+    return `Basic ${Buffer.from(raw).toString("base64")}`;
+  }
+
+  private async requestJson<T>(
+    url: string,
+    init: RequestInit,
+  ): Promise<T> {
+    this.logger?.debug?.("PmtHouse request", {
+      method: init.method ?? "GET",
+      url,
+    });
+
+    const response = await this.fetchImpl(url, init);
+    const raw = await response.text();
+    const parsed = raw ? this.safeParseJson(raw) : null;
+
+    if (!response.ok) {
+      const details = (parsed ?? {}) as Record<string, unknown>;
+      const description =
+        typeof details.error_description === "string"
+          ? details.error_description
+          : typeof details.error === "string"
+            ? details.error
+            : `Request failed (${response.status})`;
+
+      throw new PmtHouseError(description, {
+        status: response.status,
+        code:
+          typeof details.error === "string"
+            ? details.error
+            : "pymthouse_http_error",
+        details,
+      });
+    }
+
+    if (!parsed) {
+      return {} as T;
+    }
+
+    return parsed as T;
+  }
+
+  private safeParseJson(value: string): unknown {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+
+  private asError(error: unknown): PmtHouseError {
+    if (error instanceof PmtHouseError) {
+      return error;
+    }
+
+    if (error instanceof Error) {
+      return new PmtHouseError(error.message, {
+        code: "unexpected_error",
+        status: 500,
+      });
+    }
+
+    return new PmtHouseError("Unexpected error", {
+      code: "unexpected_error",
+      status: 500,
+    });
+  }
+}
diff --git a/lib/pymthouse/discovery.ts b/lib/pymthouse/discovery.ts
new file mode 100644
index 0000000..1f0cfea
--- /dev/null
+++ b/lib/pymthouse/discovery.ts
@@ -0,0 +1,76 @@
+import type { FetchLike, OidcDiscoveryDocument } from "@/lib/pymthouse/types";
+import { PmtHouseError } from "@/lib/pymthouse/errors";
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+type CacheEntry = {
+  document: OidcDiscoveryDocument;
+  fetchedAt: number;
+};
+
+const discoveryCache = new Map<string, CacheEntry>();
+
+export async function fetchDiscoveryDocument(
+  issuerUrl: string,
+  fetchImpl: FetchLike,
+): Promise<OidcDiscoveryDocument> {
+  const normalizedIssuer = issuerUrl.replace(/\/+$/, "");
+  const cached = discoveryCache.get(normalizedIssuer);
+  const now = Date.now();
+
+  if (cached && now - cached.fetchedAt < CACHE_TTL_MS) {
+    return cached.document;
+  }
+
+  const discoveryUrl =
+    `${normalizedIssuer}/.well-known/openid-configuration`;
+
+  const response = await fetchImpl(discoveryUrl, {
+    method: "GET",
+    headers: {
+      Accept: "application/json",
+    },
+    cache: "no-store",
+  });
+
+  if (!response.ok) {
+    throw new PmtHouseError(
+      `Failed to load OIDC discovery (${response.status})`,
+      {
+        status: response.status,
+        code: "oidc_discovery_failed",
+      },
+    );
+  }
+
+  const payload = (await response.json()) as Partial<OidcDiscoveryDocument>;
+
+  if (!payload.issuer || !payload.token_endpoint || !payload.jwks_uri) {
+    throw new PmtHouseError("OIDC discovery document is missing fields", {
+      status: 500,
+      code: "oidc_discovery_invalid",
+      details: payload,
+    });
+  }
+
+  const document: OidcDiscoveryDocument = {
+    issuer: payload.issuer,
+    authorization_endpoint: payload.authorization_endpoint ?? "",
+    token_endpoint: payload.token_endpoint,
+    jwks_uri: payload.jwks_uri,
+    userinfo_endpoint: payload.userinfo_endpoint,
+    device_authorization_endpoint: payload.device_authorization_endpoint,
+  };
+
+  discoveryCache.set(normalizedIssuer, { document, fetchedAt: now });
+  return document;
+}
+
+export function clearDiscoveryCache(issuerUrl?: string): void {
+  if (!issuerUrl) {
+    discoveryCache.clear();
+    return;
+  }
+
+  discoveryCache.delete(issuerUrl.replace(/\/+$/, ""));
+}
diff --git a/lib/pymthouse/errors.ts b/lib/pymthouse/errors.ts
new file mode 100644
index 0000000..7d3e6b5
--- /dev/null
+++ b/lib/pymthouse/errors.ts
@@ -0,0 +1,45 @@
+export class PmtHouseError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly details?: unknown;
+
+  constructor(
+    message: string,
+    {
+      status = 500,
+      code = "pymthouse_error",
+      details,
+    }: {
+      status?: number;
+      code?: string;
+      details?: unknown;
+    } = {},
+  ) {
+    super(message);
+    this.name = "PmtHouseError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function toPmtHouseError(
+  error: unknown,
+  fallbackMessage: string,
+): PmtHouseError {
+  if (error instanceof PmtHouseError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new PmtHouseError(error.message || fallbackMessage, {
+      code: "unexpected_error",
+      status: 500,
+    });
+  }
+
+  return new PmtHouseError(fallbackMessage, {
+    code: "unexpected_error",
+    status: 500,
+  });
+}
diff --git a/lib/pymthouse/format.ts b/lib/pymthouse/format.ts
new file mode 100644
index 0000000..efd0966
--- /dev/null
+++ b/lib/pymthouse/format.ts
@@ -0,0 +1,24 @@
+const WEI_PER_ETH = BigInt("1000000000000000000");
+
+export function formatWeiToEth(wei: string): string {
+  const weiValue = BigInt(wei || "0");
+  const whole = weiValue / WEI_PER_ETH;
+  const fraction = weiValue % WEI_PER_ETH;
+  const fractionStr = fraction.toString().padStart(18, "0").slice(0, 6);
+  if (fractionStr === "000000") {
+    return `${whole.toString()} ETH`;
+  }
+  return `${whole.toString()}.${fractionStr} ETH`;
+}
+
+export function formatWeiToUsd(
+  wei: string,
+  usdPerEth = 3500,
+): string {
+  const weiValue = BigInt(wei || "0");
+  const whole = weiValue / WEI_PER_ETH;
+  const fraction = weiValue % WEI_PER_ETH;
+  const eth = Number(whole) + Number(fraction) / 1e18;
+  const usd = eth * usdPerEth;
+  return `$${usd.toFixed(2)}`;
+}
diff --git a/lib/pymthouse/index.ts b/lib/pymthouse/index.ts
new file mode 100644
index 0000000..8d8bc12
--- /dev/null
+++ b/lib/pymthouse/index.ts
@@ -0,0 +1,20 @@
+export { PmtHouseClient } from "@/lib/pymthouse/client";
+export { PmtHouseError, toPmtHouseError } from "@/lib/pymthouse/errors";
+export { formatWeiToEth, formatWeiToUsd } from "@/lib/pymthouse/format";
+export { getPmtHouseClient } from "@/lib/pymthouse/server";
+export type {
+  AppUserRecord,
+  ClientCredentialsTokenResponse,
+  DeviceApprovalInput,
+  MintUserAccessTokenInput,
+  MintUserAccessTokenResponse,
+  OidcDiscoveryDocument,
+  ParsedDeviceApprovalRedirect,
+  PmtHouseClientOptions,
+  TokenExchangeResponse,
+  UpsertAppUserInput,
+  UsageApiResponse,
+  UsageByUserRow,
+  UsageQueryInput,
+  UsageTotals,
+} from "@/lib/pymthouse/types";
diff --git a/lib/pymthouse/server.ts b/lib/pymthouse/server.ts
new file mode 100644
index 0000000..fb7b0a5
--- /dev/null
+++ b/lib/pymthouse/server.ts
@@ -0,0 +1,41 @@
+import { PmtHouseClient } from "@/lib/pymthouse/client";
+import { PmtHouseError } from "@/lib/pymthouse/errors";
+
+let cachedClient: PmtHouseClient | null = null;
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (value && value.trim()) {
+    return value.trim();
+  }
+
+  throw new PmtHouseError(`Missing required environment variable: ${name}`, {
+    status: 500,
+    code: "missing_env",
+  });
+}
+
+export function getPmtHouseClient(): PmtHouseClient {
+  if (cachedClient) {
+    return cachedClient;
+  }
+
+  cachedClient = new PmtHouseClient({
+    issuerUrl: requiredEnv("PYMTHOUSE_ISSUER_URL"),
+    publicClientId: requiredEnv("PYMTHOUSE_PUBLIC_CLIENT_ID"),
+    m2mClientId: requiredEnv("PYMTHOUSE_M2M_CLIENT_ID"),
+    m2mClientSecret: requiredEnv("PYMTHOUSE_M2M_CLIENT_SECRET"),
+    logger: {
+      debug: (message, details) => {
+        if (process.env.NODE_ENV !== "production") {
+          console.debug(`[pymthouse] ${message}`, details ?? {});
+        }
+      },
+      warn: (message, details) => {
+        console.warn(`[pymthouse] ${message}`, details ?? {});
+      },
+    },
+  });
+
+  return cachedClient;
+}
diff --git a/lib/pymthouse/types.ts b/lib/pymthouse/types.ts
new file mode 100644
index 0000000..33d8ffd
--- /dev/null
+++ b/lib/pymthouse/types.ts
@@ -0,0 +1,115 @@
+export type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface OidcDiscoveryDocument {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  jwks_uri: string;
+  userinfo_endpoint?: string;
+  device_authorization_endpoint?: string;
+}
+
+export interface PmtHouseClientOptions {
+  issuerUrl: string;
+  publicClientId: string;
+  m2mClientId: string;
+  m2mClientSecret: string;
+  fetch?: FetchLike;
+  logger?: {
+    debug?: (message: string, details?: Record<string, unknown>) => void;
+    warn?: (message: string, details?: Record<string, unknown>) => void;
+  };
+}
+
+export interface UpsertAppUserInput {
+  externalUserId: string;
+  email?: string;
+  status?: "active" | "inactive";
+}
+
+export interface AppUserRecord {
+  id: string;
+  clientId: string;
+  externalUserId: string;
+  email: string | null;
+  status: string;
+  role: string;
+  createdAt: string;
+}
+
+export interface MintUserAccessTokenInput {
+  externalUserId: string;
+  scope?: string;
+}
+
+export interface MintUserAccessTokenResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type: "Bearer";
+  expires_in: number;
+  scope: string;
+  subject_type: "app_user";
+  correlation_id?: string;
+}
+
+export interface DeviceApprovalInput {
+  userJwt: string;
+  userCode: string;
+}
+
+export interface TokenExchangeResponse {
+  access_token: string;
+  token_type: "Bearer";
+  expires_in: number;
+  scope: string;
+  issued_token_type: string;
+}
+
+export interface UsageQueryInput {
+  startDate?: string;
+  endDate?: string;
+  groupBy?: "none" | "user";
+  userId?: string;
+}
+
+export interface UsageTotals {
+  requestCount: number;
+  totalFeeWei: string;
+}
+
+export interface UsageByUserRow {
+  endUserId: string;
+  externalUserId: string | null;
+  requestCount: number;
+  feeWei: string;
+  userType?: "system_managed" | "oidc_authorized" | "unknown";
+  identifier?: string;
+}
+
+export interface UsageApiResponse {
+  clientId: string;
+  period: {
+    start: string | null;
+    end: string | null;
+  };
+  totals: UsageTotals;
+  byUser?: UsageByUserRow[];
+}
+
+export interface ClientCredentialsTokenResponse {
+  access_token: string;
+  token_type: "Bearer";
+  expires_in?: number;
+  scope?: string;
+  [key: string]: unknown;
+}
+
+export interface ParsedDeviceApprovalRedirect {
+  issuer: string;
+  targetLinkUri: string;
+  userCode: string;
+  clientId: string;
+}
diff --git a/lib/session.ts b/lib/session.ts
new file mode 100644
index 0000000..e001b61
--- /dev/null
+++ b/lib/session.ts
@@ -0,0 +1,326 @@
+import { SignJWT, jwtVerify, type JWTPayload } from "jose";
+import type { NextRequest, NextResponse } from "next/server";
+
+export const SESSION_COOKIE_NAME = "lp_session";
+export const SESSION_USER_COOKIE_NAME = "lp_session_user";
+export const BROWSER_JWT_COOKIE_NAME = "lp_browser_jwt";
+export const DEVICE_FLOW_COOKIE_NAME = "lp_device_flow";
+
+const SESSION_TTL_SECONDS = 60 * 60 * 24 * 7;
+const BROWSER_JWT_TTL_SECONDS = 60 * 15;
+const DEVICE_FLOW_TTL_SECONDS = 60 * 10;
+
+type StudioAuthProvider = "github" | "google" | "email";
+
+export type StoredApiTokenMeta = {
+  id: string;
+  name: string;
+  prefix: string;
+  createdAt: string;
+  lastUsedAt: string | null;
+  status: "active" | "revoked";
+};
+
+export interface SessionPayload extends JWTPayload {
+  sub: string;
+  externalUserId: string;
+  email: string;
+  name: string;
+  initials: string;
+  provider: StudioAuthProvider;
+  pmthUserJwt: string;
+  apiTokens: StoredApiTokenMeta[];
+}
+
+export interface SessionPublicUser {
+  externalUserId: string;
+  email: string;
+  name: string;
+  initials: string;
+  provider: StudioAuthProvider;
+  hasPmthouseBinding: boolean;
+}
+
+export interface IssueSessionInput {
+  externalUserId: string;
+  email: string;
+  name: string;
+  initials: string;
+  provider: StudioAuthProvider;
+  pmthUserJwt: string;
+  apiTokens?: StoredApiTokenMeta[];
+}
+
+export interface DeviceFlowPayload extends JWTPayload {
+  iss: string;
+  targetLinkUri: string;
+  userCode: string;
+  clientId: string;
+}
+
+function getSessionSecret(): Uint8Array {
+  const raw = process.env.LP_SESSION_SECRET;
+  if (raw && raw.trim()) {
+    return new TextEncoder().encode(raw.trim());
+  }
+
+  if (process.env.NODE_ENV === "production") {
+    throw new Error("LP_SESSION_SECRET is required in production");
+  }
+
+  return new TextEncoder().encode("dev-only-unsafe-session-secret");
+}
+
+async function signJwt(
+  payload: JWTPayload,
+  expiresInSeconds: number,
+): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  return new SignJWT(payload)
+    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
+    .setIssuedAt(now)
+    .setExpirationTime(now + expiresInSeconds)
+    .sign(getSessionSecret());
+}
+
+export async function createSessionToken(
+  input: IssueSessionInput,
+): Promise<string> {
+  const payload: SessionPayload = {
+    sub: input.externalUserId,
+    externalUserId: input.externalUserId,
+    email: input.email,
+    name: input.name,
+    initials: input.initials,
+    provider: input.provider,
+    pmthUserJwt: input.pmthUserJwt,
+    apiTokens: input.apiTokens ?? [],
+  };
+  return signJwt(payload, SESSION_TTL_SECONDS);
+}
+
+export async function createBrowserJwt(
+  payload: SessionPublicUser,
+): Promise<string> {
+  return signJwt(
+    {
+      sub: payload.externalUserId,
+      email: payload.email,
+      name: payload.name,
+      initials: payload.initials,
+      provider: payload.provider,
+      hasPmthouseBinding: payload.hasPmthouseBinding,
+      aud: "studio-browser",
+    },
+    BROWSER_JWT_TTL_SECONDS,
+  );
+}
+
+export async function verifySessionToken(
+  token: string,
+): Promise<SessionPayload | null> {
+  try {
+    const { payload } = await jwtVerify(token, getSessionSecret(), {
+      algorithms: ["HS256"],
+    });
+    if (
+      typeof payload.sub !== "string" ||
+      typeof payload.externalUserId !== "string" ||
+      typeof payload.pmthUserJwt !== "string"
+    ) {
+      return null;
+    }
+
+    return {
+      ...payload,
+      sub: payload.sub,
+      externalUserId: payload.externalUserId,
+      email: String(payload.email ?? ""),
+      name: String(payload.name ?? ""),
+      initials: String(payload.initials ?? ""),
+      provider: (payload.provider as StudioAuthProvider) ?? "email",
+      pmthUserJwt: payload.pmthUserJwt,
+      apiTokens: Array.isArray(payload.apiTokens)
+        ? (payload.apiTokens as StoredApiTokenMeta[])
+        : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function createDeviceFlowToken(
+  payload: Omit<DeviceFlowPayload, "iat" | "exp">,
+): Promise<string> {
+  return signJwt(payload, DEVICE_FLOW_TTL_SECONDS);
+}
+
+export async function verifyDeviceFlowToken(
+  token: string,
+): Promise<DeviceFlowPayload | null> {
+  try {
+    const { payload } = await jwtVerify(token, getSessionSecret(), {
+      algorithms: ["HS256"],
+    });
+    if (
+      typeof payload.iss !== "string" ||
+      typeof payload.targetLinkUri !== "string" ||
+      typeof payload.userCode !== "string" ||
+      typeof payload.clientId !== "string"
+    ) {
+      return null;
+    }
+
+    return {
+      ...payload,
+      iss: payload.iss,
+      targetLinkUri: payload.targetLinkUri,
+      userCode: payload.userCode,
+      clientId: payload.clientId,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function readSessionFromRequest(
+  request: NextRequest,
+): Promise<SessionPayload | null> {
+  const token = request.cookies.get(SESSION_COOKIE_NAME)?.value;
+  if (!token) {
+    return null;
+  }
+  return verifySessionToken(token);
+}
+
+export async function readDeviceFlowFromRequest(
+  request: NextRequest,
+): Promise<DeviceFlowPayload | null> {
+  const token = request.cookies.get(DEVICE_FLOW_COOKIE_NAME)?.value;
+  if (!token) {
+    return null;
+  }
+  return verifyDeviceFlowToken(token);
+}
+
+export function toSessionPublicUser(payload: SessionPayload): SessionPublicUser {
+  return {
+    externalUserId: payload.externalUserId,
+    email: payload.email,
+    name: payload.name,
+    initials: payload.initials,
+    provider: payload.provider,
+    hasPmthouseBinding: Boolean(payload.pmthUserJwt),
+  };
+}
+
+export async function applySessionCookies(
+  response: NextResponse,
+  input: IssueSessionInput,
+): Promise<void> {
+  const sessionToken = await createSessionToken(input);
+  const publicUser = toSessionPublicUser({
+    ...input,
+    sub: input.externalUserId,
+    apiTokens: input.apiTokens ?? [],
+  });
+  const browserJwt = await createBrowserJwt(publicUser);
+
+  const secure = process.env.NODE_ENV === "production";
+  response.cookies.set(SESSION_COOKIE_NAME, sessionToken, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure,
+    path: "/",
+    maxAge: SESSION_TTL_SECONDS,
+  });
+  response.cookies.set(
+    SESSION_USER_COOKIE_NAME,
+    Buffer.from(JSON.stringify(publicUser), "utf-8").toString("base64"),
+    {
+    httpOnly: false,
+    sameSite: "lax",
+    secure,
+    path: "/",
+    maxAge: SESSION_TTL_SECONDS,
+    },
+  );
+  response.cookies.set(BROWSER_JWT_COOKIE_NAME, browserJwt, {
+    httpOnly: false,
+    sameSite: "lax",
+    secure,
+    path: "/",
+    maxAge: BROWSER_JWT_TTL_SECONDS,
+  });
+}
+
+export function clearSessionCookies(response: NextResponse): void {
+  response.cookies.set(SESSION_COOKIE_NAME, "", {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: process.env.NODE_ENV === "production",
+    path: "/",
+    maxAge: 0,
+  });
+  response.cookies.set(SESSION_USER_COOKIE_NAME, "", {
+    httpOnly: false,
+    sameSite: "lax",
+    secure: process.env.NODE_ENV === "production",
+    path: "/",
+    maxAge: 0,
+  });
+  response.cookies.set(BROWSER_JWT_COOKIE_NAME, "", {
+    httpOnly: false,
+    sameSite: "lax",
+    secure: process.env.NODE_ENV === "production",
+    path: "/",
+    maxAge: 0,
+  });
+  clearDeviceFlowCookie(response);
+}
+
+export async function setDeviceFlowCookie(
+  response: NextResponse,
+  payload: Omit<DeviceFlowPayload, "iat" | "exp">,
+): Promise<void> {
+  const token = await createDeviceFlowToken(payload);
+  response.cookies.set(DEVICE_FLOW_COOKIE_NAME, token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: process.env.NODE_ENV === "production",
+    path: "/",
+    maxAge: DEVICE_FLOW_TTL_SECONDS,
+  });
+}
+
+export function clearDeviceFlowCookie(response: NextResponse): void {
+  response.cookies.set(DEVICE_FLOW_COOKIE_NAME, "", {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: process.env.NODE_ENV === "production",
+    path: "/",
+    maxAge: 0,
+  });
+}
+
+export function upsertApiTokenMeta(
+  payload: SessionPayload,
+  token: StoredApiTokenMeta,
+): StoredApiTokenMeta[] {
+  const filtered = payload.apiTokens.filter((item) => item.id !== token.id);
+  return [...filtered, token];
+}
+
+export function revokeApiTokenMeta(
+  payload: SessionPayload,
+  tokenId: string,
+): StoredApiTokenMeta[] {
+  return payload.apiTokens.map((item) =>
+    item.id === tokenId
+      ? {
+          ...item,
+          status: "revoked",
+        }
+      : item,
+  );
+}
diff --git a/lib/studio-auth.ts b/lib/studio-auth.ts
new file mode 100644
index 0000000..1417df9
--- /dev/null
+++ b/lib/studio-auth.ts
@@ -0,0 +1,63 @@
+import { createHash } from "crypto";
+
+export type StudioAuthProvider = "github" | "google" | "email";
+
+export interface StudioLoginProfile {
+  provider: StudioAuthProvider;
+  name: string;
+  email: string;
+  initials: string;
+}
+
+const MOCK_PROVIDER_PROFILES: Record<
+  Exclude<StudioAuthProvider, "email">,
+  { name: string; email: string }
+> = {
+  github: {
+    name: "Studio Developer",
+    email: "studio.github@example.com",
+  },
+  google: {
+    name: "Studio Developer",
+    email: "studio.google@example.com",
+  },
+};
+
+export function toInitials(name: string): string {
+  return name
+    .split(" ")
+    .map((word) => word.trim())
+    .filter(Boolean)
+    .map((word) => word[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2) || "SU";
+}
+
+export function deriveExternalUserId(email: string): string {
+  const digest = createHash("sha256")
+    .update(email.trim().toLowerCase())
+    .digest("hex")
+    .slice(0, 24);
+  return `ext_${digest}`;
+}
+
+export function resolveLoginProfile(input: {
+  provider: StudioAuthProvider;
+  email?: string;
+  name?: string;
+}): StudioLoginProfile {
+  const provider = input.provider;
+  const fallback = provider === "email" ? null : MOCK_PROVIDER_PROFILES[provider];
+
+  const email = input.email?.trim() || fallback?.email || "studio.user@example.com";
+  const displayName =
+    input.name?.trim() || fallback?.name || email.split("@")[0] || "Studio User";
+
+  return {
+    provider,
+    name: displayName,
+    email,
+    initials: toInitials(displayName),
+  };
+}
diff --git a/package.json b/package.json
index f80defd..dfae896 100644
--- a/package.json
+++ b/package.json
@@ -15,6 +15,7 @@
   "dependencies": {
     "framer-motion": "^11.15.0",
     "gray-matter": "^4.0.3",
+    "jose": "^6.2.2",
     "lucide-react": "^1.6.0",
     "next": "^15.1.0",
     "react": "^19.0.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 13cfc55..be71e63 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -14,6 +14,9 @@ importers:
       gray-matter:
         specifier: ^4.0.3
         version: 4.0.3
+      jose:
+        specifier: ^6.2.2
+        version: 6.2.2
       lucide-react:
         specifier: ^1.6.0
         version: 1.7.0(react@19.2.4)
@@ -1079,19 +1082,14 @@ packages:
       typescript:
         optional: true
 
-<<<<<<< Updated upstream
   eslint-config-prettier@10.1.8:
     resolution: {integrity: sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==}
     hasBin: true
     peerDependencies:
       eslint: '>=7.0.0'
 
-  eslint-import-resolver-node@0.3.9:
-    resolution: {integrity: sha512-WFj2isz22JahUv+B788TlO3N6zL3nNJGU8CcZbPZvVEkBPaJdCV4vy5wyghty5ROFbCRnm132v8BScu5/1BQ8g==}
-=======
   eslint-import-resolver-node@0.3.10:
     resolution: {integrity: sha512-tRrKqFyCaKict5hOd244sL6EQFNycnMQnBe+j8uqGNXYzsImGbGUU4ibtoaBmv5FLwJwcFJNeg1GeVjQfbMrDQ==}
->>>>>>> Stashed changes
 
   eslint-import-resolver-typescript@3.10.1:
     resolution: {integrity: sha512-A1rHYb06zjMGAxdLSkN2fXPBwuSaQ0iO5M/hdyS0Ajj1VBaRp0sPD3dn1FhME3c/JluGFbwSxyCfqdSbtQLAHQ==}
@@ -1535,6 +1533,9 @@ packages:
     resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
     hasBin: true
 
+  jose@6.2.2:
+    resolution: {integrity: sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ==}
+
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
@@ -3266,15 +3267,11 @@ snapshots:
       - eslint-plugin-import-x
       - supports-color
 
-<<<<<<< Updated upstream
   eslint-config-prettier@10.1.8(eslint@9.39.4(jiti@2.6.1)):
     dependencies:
       eslint: 9.39.4(jiti@2.6.1)
 
-  eslint-import-resolver-node@0.3.9:
-=======
   eslint-import-resolver-node@0.3.10:
->>>>>>> Stashed changes
     dependencies:
       debug: 3.2.7
       is-core-module: 2.16.1
@@ -3795,6 +3792,8 @@ snapshots:
 
   jiti@2.6.1: {}
 
+  jose@6.2.2: {}
+
   js-tokens@4.0.0: {}
 
   js-yaml@3.14.2:

From c54caf3282c18e38855da1cd3ba66fe60cbb0bd3 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sun, 19 Apr 2026 20:28:01 -0400
Subject: [PATCH 2/5] feat: refactor device approval flow and enhance session
 management

Updated the device approval process by introducing a new utility function for completing studio device approvals with Pymthouse. This change centralizes the logic for user approval and JWT minting, improving code maintainability. Enhanced session management by applying session cookies consistently across device approval routes. Adjusted the login page to handle device flow more effectively, ensuring a smoother user experience during authentication.
---
 app/api/auth/device/complete/route.ts         | 20 ++++--
 app/api/auth/initiate-login/route.ts          | 15 ++++-
 app/api/auth/login/route.ts                   | 67 +++++--------------
 components/studio/LoginPage.tsx               | 25 ++++++-
 .../complete-studio-device-approval.ts        | 44 ++++++++++++
 5 files changed, 112 insertions(+), 59 deletions(-)
 create mode 100644 lib/pymthouse/complete-studio-device-approval.ts

diff --git a/app/api/auth/device/complete/route.ts b/app/api/auth/device/complete/route.ts
index 607221d..edd8f33 100644
--- a/app/api/auth/device/complete/route.ts
+++ b/app/api/auth/device/complete/route.ts
@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from "next/server";
-import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
+import { PmtHouseError } from "@/lib/pymthouse";
+import { completeStudioDeviceApprovalWithPymthouse } from "@/lib/pymthouse/complete-studio-device-approval";
 import {
+  applySessionCookies,
   clearDeviceFlowCookie,
   readDeviceFlowFromRequest,
   readSessionFromRequest,
@@ -30,9 +32,8 @@ export async function POST(request: NextRequest) {
   }
 
   try {
-    const client = getPmtHouseClient();
-    await client.completeDeviceApproval({
-      userJwt: session.pmthUserJwt,
+    const pmthUserJwt = await completeStudioDeviceApprovalWithPymthouse({
+      session,
       userCode: deviceFlow.userCode,
     });
 
@@ -40,6 +41,17 @@ export async function POST(request: NextRequest) {
       success: true,
       redirectTo: "/studio/device-approved",
     });
+
+    await applySessionCookies(response, {
+      externalUserId: session.externalUserId,
+      email: session.email,
+      name: session.name,
+      initials: session.initials,
+      provider: session.provider,
+      pmthUserJwt,
+      apiTokens: session.apiTokens,
+    });
+
     clearDeviceFlowCookie(response);
     return response;
   } catch (error) {
diff --git a/app/api/auth/initiate-login/route.ts b/app/api/auth/initiate-login/route.ts
index cc5a610..ccbdd8a 100644
--- a/app/api/auth/initiate-login/route.ts
+++ b/app/api/auth/initiate-login/route.ts
@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from "next/server";
 import { getPmtHouseClient } from "@/lib/pymthouse";
+import { completeStudioDeviceApprovalWithPymthouse } from "@/lib/pymthouse/complete-studio-device-approval";
 import {
+  applySessionCookies,
   clearDeviceFlowCookie,
   readSessionFromRequest,
   setDeviceFlowCookie,
@@ -27,13 +29,22 @@ export async function GET(request: NextRequest) {
       return response;
     }
 
-    await client.completeDeviceApproval({
-      userJwt: session.pmthUserJwt,
+    const pmthUserJwt = await completeStudioDeviceApprovalWithPymthouse({
+      session,
       userCode: parsed.userCode,
     });
 
     const approvedUrl = new URL("/studio/device-approved", request.url);
     const response = NextResponse.redirect(approvedUrl);
+    await applySessionCookies(response, {
+      externalUserId: session.externalUserId,
+      email: session.email,
+      name: session.name,
+      initials: session.initials,
+      provider: session.provider,
+      pmthUserJwt,
+      apiTokens: session.apiTokens,
+    });
     clearDeviceFlowCookie(response);
     return response;
   } catch (error) {
diff --git a/app/api/auth/login/route.ts b/app/api/auth/login/route.ts
index 5d70742..7f3ee80 100644
--- a/app/api/auth/login/route.ts
+++ b/app/api/auth/login/route.ts
@@ -1,10 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
-import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
-import {
-  applySessionCookies,
-  clearDeviceFlowCookie,
-  readDeviceFlowFromRequest,
-} from "@/lib/session";
+import { applySessionCookies } from "@/lib/session";
 import {
   deriveExternalUserId,
   resolveLoginProfile,
@@ -20,6 +15,11 @@ function toProvider(value: unknown): StudioAuthProvider {
   return "email";
 }
 
+/**
+ * Studio sign-in: website-only stub session. No Pymthouse.
+ * Device approval uses Pymthouse only from `/api/auth/device/complete` or
+ * `GET /api/auth/initiate-login` when a session already exists.
+ */
 export async function POST(request: NextRequest) {
   try {
     const body = (await request.json().catch(() => ({}))) as Record<string, unknown>;
@@ -30,43 +30,20 @@ export async function POST(request: NextRequest) {
       name: typeof body.name === "string" ? body.name : undefined,
     });
 
-    const client = getPmtHouseClient();
     const externalUserId = deriveExternalUserId(profile.email);
 
-    await client.upsertAppUser({
-      externalUserId,
+    const userPayload = {
+      name: profile.name,
       email: profile.email,
-      status: "active",
-    });
-
-    const userToken = await client.mintUserAccessToken({
-      externalUserId,
-      scope: "sign:job",
-    });
-
-    const deviceFlow = await readDeviceFlowFromRequest(request);
-    let redirectTo = "/studio";
-    let deviceApproved = false;
-
-    if (deviceFlow) {
-      await client.completeDeviceApproval({
-        userJwt: userToken.access_token,
-        userCode: deviceFlow.userCode,
-      });
-      redirectTo = "/studio/device-approved";
-      deviceApproved = true;
-    }
+      initials: profile.initials,
+      provider: profile.provider,
+    };
 
     const response = NextResponse.json({
       success: true,
-      redirectTo,
-      deviceApproved,
-      user: {
-        name: profile.name,
-        email: profile.email,
-        initials: profile.initials,
-        provider: profile.provider,
-      },
+      redirectTo: "/studio",
+      deviceApproved: false,
+      user: userPayload,
     });
 
     await applySessionCookies(response, {
@@ -75,26 +52,12 @@ export async function POST(request: NextRequest) {
       name: profile.name,
       initials: profile.initials,
       provider: profile.provider,
-      pmthUserJwt: userToken.access_token,
+      pmthUserJwt: "",
     });
 
-    if (deviceFlow) {
-      clearDeviceFlowCookie(response);
-    }
-
     return response;
   } catch (error) {
     console.error("Studio login failed", error);
-    if (error instanceof PmtHouseError) {
-      return NextResponse.json(
-        {
-          error: error.code,
-          error_description: error.message,
-        },
-        { status: error.status },
-      );
-    }
-
     return NextResponse.json(
       {
         error: "login_failed",
diff --git a/components/studio/LoginPage.tsx b/components/studio/LoginPage.tsx
index 8aae5c5..9c9ddc1 100644
--- a/components/studio/LoginPage.tsx
+++ b/components/studio/LoginPage.tsx
@@ -92,7 +92,30 @@ export default function LoginPage() {
 
       connect(json.user);
       await refresh();
-      router.push(json.redirectTo || "/studio");
+
+      let nextPath = json.redirectTo || "/studio";
+      if (deviceFlow) {
+        const deviceRes = await fetch("/api/auth/device/complete", {
+          method: "POST",
+          credentials: "include",
+        });
+        const deviceJson = (await deviceRes.json().catch(() => ({}))) as {
+          success?: boolean;
+          error_description?: string;
+          redirectTo?: string;
+        };
+        if (!deviceRes.ok || !deviceJson.success) {
+          setSubmitError(
+            deviceJson.error_description ||
+              "Could not complete device approval with Pymthouse.",
+          );
+          return;
+        }
+        await refresh();
+        nextPath = deviceJson.redirectTo || "/studio/device-approved";
+      }
+
+      router.push(nextPath);
     } catch {
       setSubmitError("Could not sign in. Please try again.");
     } finally {
diff --git a/lib/pymthouse/complete-studio-device-approval.ts b/lib/pymthouse/complete-studio-device-approval.ts
new file mode 100644
index 0000000..ae082c2
--- /dev/null
+++ b/lib/pymthouse/complete-studio-device-approval.ts
@@ -0,0 +1,44 @@
+import { getPmtHouseClient } from "@/lib/pymthouse/server";
+import { PmtHouseError } from "@/lib/pymthouse/errors";
+import type { SessionPayload } from "@/lib/session";
+
+/**
+ * Studio device flow only: upsert app user, mint user JWT, RFC 8693 device approval.
+ * Not used for normal `/api/auth/login` (website stub session).
+ */
+export async function completeStudioDeviceApprovalWithPymthouse(params: {
+  session: SessionPayload;
+  userCode: string;
+}): Promise<string> {
+  if (
+    !process.env.PYMTHOUSE_ISSUER_URL?.trim() ||
+    !process.env.PYMTHOUSE_PUBLIC_CLIENT_ID?.trim() ||
+    !process.env.PYMTHOUSE_M2M_CLIENT_ID?.trim() ||
+    !process.env.PYMTHOUSE_M2M_CLIENT_SECRET?.trim()
+  ) {
+    throw new PmtHouseError(
+      "Pymthouse is not configured. Set PYMTHOUSE_* environment variables.",
+      { status: 503, code: "pymthouse_required" },
+    );
+  }
+
+  const client = getPmtHouseClient();
+
+  await client.upsertAppUser({
+    externalUserId: params.session.externalUserId,
+    email: params.session.email,
+    status: "active",
+  });
+
+  const userToken = await client.mintUserAccessToken({
+    externalUserId: params.session.externalUserId,
+    scope: "sign:job",
+  });
+
+  await client.completeDeviceApproval({
+    userJwt: userToken.access_token,
+    userCode: params.userCode,
+  });
+
+  return userToken.access_token;
+}

From 59afb97b5ee80c2c85394c5bd2f6d7512f5769aa Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sun, 19 Apr 2026 23:26:49 -0400
Subject: [PATCH 3/5] feat: update PymtHouse integration and clean up
 environment configuration

Enhanced the PymtHouse integration by adding a new dependency for the builder API and updating the environment configuration in `.env.example`. Improved the `.gitignore` to exclude certificate files. Refactored API routes to utilize the new builder API for device approval and session management, ensuring a more streamlined authentication process. Removed outdated PmtHouse client code and related files to simplify the codebase.
---
 .env.example                                  |   1 +
 .gitignore                                    |   2 +
 app/api/auth/device/complete/route.ts         |   4 +-
 app/api/auth/initiate-login/route.ts          |   6 +-
 app/api/tokens/route.ts                       |   5 +-
 app/api/usage/route.ts                        |   7 +-
 ...oval.ts => pmth-studio-device-approval.ts} |   6 +-
 lib/pymthouse/README.md                       | 203 ----------
 lib/pymthouse/client.ts                       | 351 ------------------
 lib/pymthouse/discovery.ts                    |  76 ----
 lib/pymthouse/errors.ts                       |  45 ---
 lib/pymthouse/format.ts                       |  24 --
 lib/pymthouse/index.ts                        |  20 -
 lib/pymthouse/server.ts                       |  41 --
 lib/pymthouse/types.ts                        | 115 ------
 package.json                                  |   1 +
 pnpm-lock.yaml                                |  16 +
 17 files changed, 35 insertions(+), 888 deletions(-)
 rename lib/{pymthouse/complete-studio-device-approval.ts => pmth-studio-device-approval.ts} (86%)
 delete mode 100644 lib/pymthouse/README.md
 delete mode 100644 lib/pymthouse/client.ts
 delete mode 100644 lib/pymthouse/discovery.ts
 delete mode 100644 lib/pymthouse/errors.ts
 delete mode 100644 lib/pymthouse/format.ts
 delete mode 100644 lib/pymthouse/index.ts
 delete mode 100644 lib/pymthouse/server.ts
 delete mode 100644 lib/pymthouse/types.ts

diff --git a/.env.example b/.env.example
index 3f64356..7459089 100644
--- a/.env.example
+++ b/.env.example
@@ -8,6 +8,7 @@ THEGRAPH_API_KEY=
 
 # PymtHouse integration (required for Studio auth/device flow)
 # Issuer must be the full OIDC issuer URL, e.g. http://localhost:3001/api/v1/oidc
+# (site origin is derived from this URL in code — no PMTHOUSE_BASE_URL)
 PYMTHOUSE_ISSUER_URL=
 # Public OIDC client id (app_...)
 PYMTHOUSE_PUBLIC_CLIENT_ID=
diff --git a/.gitignore b/.gitignore
index 219d8bd..41ec2d2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -50,3 +50,5 @@ img/
 .vscode/
 *.code-workspace
 .playwright-mcp/
+
+certificates
\ No newline at end of file
diff --git a/app/api/auth/device/complete/route.ts b/app/api/auth/device/complete/route.ts
index edd8f33..09f6d24 100644
--- a/app/api/auth/device/complete/route.ts
+++ b/app/api/auth/device/complete/route.ts
@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from "next/server";
-import { PmtHouseError } from "@/lib/pymthouse";
-import { completeStudioDeviceApprovalWithPymthouse } from "@/lib/pymthouse/complete-studio-device-approval";
+import { PmtHouseError } from "@pymthouse/builder-api";
+import { completeStudioDeviceApprovalWithPymthouse } from "@/lib/pmth-studio-device-approval";
 import {
   applySessionCookies,
   clearDeviceFlowCookie,
diff --git a/app/api/auth/initiate-login/route.ts b/app/api/auth/initiate-login/route.ts
index ccbdd8a..5514524 100644
--- a/app/api/auth/initiate-login/route.ts
+++ b/app/api/auth/initiate-login/route.ts
@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from "next/server";
-import { getPmtHouseClient } from "@/lib/pymthouse";
-import { completeStudioDeviceApprovalWithPymthouse } from "@/lib/pymthouse/complete-studio-device-approval";
+import { createPmtHouseClientFromEnv } from "@pymthouse/builder-api/env";
+import { completeStudioDeviceApprovalWithPymthouse } from "@/lib/pmth-studio-device-approval";
 import {
   applySessionCookies,
   clearDeviceFlowCookie,
@@ -12,7 +12,7 @@ export const runtime = "nodejs";
 
 export async function GET(request: NextRequest) {
   try {
-    const client = getPmtHouseClient();
+    const client = createPmtHouseClientFromEnv();
     const parsed = client.parseDeviceApprovalRedirect(request.nextUrl.searchParams);
     const session = await readSessionFromRequest(request);
 
diff --git a/app/api/tokens/route.ts b/app/api/tokens/route.ts
index 0570c40..827b03f 100644
--- a/app/api/tokens/route.ts
+++ b/app/api/tokens/route.ts
@@ -1,6 +1,7 @@
 import { randomUUID } from "crypto";
 import { NextRequest, NextResponse } from "next/server";
-import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
+import { PmtHouseError } from "@pymthouse/builder-api";
+import { createPmtHouseClientFromEnv } from "@pymthouse/builder-api/env";
 import {
   applySessionCookies,
   readSessionFromRequest,
@@ -39,7 +40,7 @@ export async function POST(request: NextRequest) {
         ? body.name.trim()
         : "Token";
 
-    const client = getPmtHouseClient();
+    const client = createPmtHouseClientFromEnv();
     const tokenResponse = await client.createSignerSessionToken({
       userJwt: session.pmthUserJwt,
     });
diff --git a/app/api/usage/route.ts b/app/api/usage/route.ts
index 15d6b99..8dbad41 100644
--- a/app/api/usage/route.ts
+++ b/app/api/usage/route.ts
@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
-import { formatWeiToUsd } from "@/lib/pymthouse/format";
-import { getPmtHouseClient, PmtHouseError } from "@/lib/pymthouse";
+import { PmtHouseError } from "@pymthouse/builder-api";
+import { createPmtHouseClientFromEnv } from "@pymthouse/builder-api/env";
+import { formatWeiToUsd } from "@pymthouse/builder-api/format";
 import { readSessionFromRequest } from "@/lib/session";
 
 export const runtime = "nodejs";
@@ -53,7 +54,7 @@ export async function GET(request: NextRequest) {
   const { days, startDate, endDate } = getPeriodWindow(period);
 
   try {
-    const client = getPmtHouseClient();
+    const client = createPmtHouseClientFromEnv();
     const usage = await client.getUsage({
       startDate,
       endDate,
diff --git a/lib/pymthouse/complete-studio-device-approval.ts b/lib/pmth-studio-device-approval.ts
similarity index 86%
rename from lib/pymthouse/complete-studio-device-approval.ts
rename to lib/pmth-studio-device-approval.ts
index ae082c2..67c9e23 100644
--- a/lib/pymthouse/complete-studio-device-approval.ts
+++ b/lib/pmth-studio-device-approval.ts
@@ -1,5 +1,5 @@
-import { getPmtHouseClient } from "@/lib/pymthouse/server";
-import { PmtHouseError } from "@/lib/pymthouse/errors";
+import { PmtHouseError } from "@pymthouse/builder-api";
+import { createPmtHouseClientFromEnv } from "@pymthouse/builder-api/env";
 import type { SessionPayload } from "@/lib/session";
 
 /**
@@ -22,7 +22,7 @@ export async function completeStudioDeviceApprovalWithPymthouse(params: {
     );
   }
 
-  const client = getPmtHouseClient();
+  const client = createPmtHouseClientFromEnv();
 
   await client.upsertAppUser({
     externalUserId: params.session.externalUserId,
diff --git a/lib/pymthouse/README.md b/lib/pymthouse/README.md
deleted file mode 100644
index e0a5368..0000000
--- a/lib/pymthouse/README.md
+++ /dev/null
@@ -1,203 +0,0 @@
-# PmtHouse SDK Integration (Website)
-
-This module provides a server-safe, SDK-style integration layer for PymtHouse in the `website` app. It is designed to be reusable, typed, and explicit about OAuth/OIDC boundaries.
-
-The implementation follows the contracts in:
-
-- [`pymthouse/docs/builder-api.md`](/home/elite/repos/pymthouse/docs/builder-api.md)
-- [`pymthouse/docs/naap-oidc-integration.md`](/home/elite/repos/pymthouse/docs/naap-oidc-integration.md)
-- [`pymthouse/docs/usage-api.md`](/home/elite/repos/pymthouse/docs/usage-api.md)
-
-## Standards Alignment
-
-The flow uses the same standards and grant types documented by PymtHouse:
-
-- OAuth 2.0 (RFC 6749)
-- Bearer token usage (RFC 6750)
-- Device Authorization Grant (RFC 8628)
-- Token Exchange (RFC 8693)
-- Resource Indicators (RFC 8707)
-- JWT access token profile (RFC 9068)
-
-## Environment Configuration
-
-Set the following in your runtime environment:
-
-```bash
-PYMTHOUSE_ISSUER_URL=http://localhost:3001/api/v1/oidc
-PYMTHOUSE_PUBLIC_CLIENT_ID=app_...
-PYMTHOUSE_M2M_CLIENT_ID=m2m_...
-PYMTHOUSE_M2M_CLIENT_SECRET=pmth_cs_...
-LP_SESSION_SECRET=<openssl rand -base64 32>
-```
-
-Notes:
-
-- `PYMTHOUSE_PUBLIC_CLIENT_ID` is the `app_...` client used in Builder path tenancy (`/api/v1/apps/{clientId}/...`).
-- `PYMTHOUSE_M2M_CLIENT_ID` / `PYMTHOUSE_M2M_CLIENT_SECRET` authenticate confidential server-to-server calls.
-
-## Module Layout
-
-- `client.ts`: Main `PmtHouseClient` class
-- `discovery.ts`: OIDC discovery fetch + cache
-- `errors.ts`: structured `PmtHouseError`
-- `types.ts`: request/response types
-- `format.ts`: wei formatting helpers
-- `server.ts`: singleton factory (`getPmtHouseClient()`)
-
-## Typical Usage
-
-```ts
-import { getPmtHouseClient } from "@/lib/pymthouse";
-
-const client = getPmtHouseClient();
-const discovery = await client.getDiscovery();
-console.log(discovery.issuer);
-```
-
-## API Reference
-
-### `getDiscovery()`
-
-Fetches and caches `{issuer}/.well-known/openid-configuration`.
-
-```ts
-const metadata = await client.getDiscovery();
-```
-
-### `verifyIssuer(iss)`
-
-Exact issuer match guard used for third-party initiate-login callbacks.
-
-```ts
-if (!client.verifyIssuer(issFromQuery)) {
-  throw new Error("Issuer mismatch");
-}
-```
-
-### `parseDeviceApprovalRedirect(searchParams)`
-
-Parses and validates `iss` + `target_link_uri`, and extracts `user_code`/`client_id`.
-
-```ts
-const parsed = client.parseDeviceApprovalRedirect(request.nextUrl.searchParams);
-// parsed.userCode -> normalized RFC 8628 user code
-```
-
-### `upsertAppUser({ externalUserId, email, status })`
-
-Calls Builder API `POST /api/v1/apps/{clientId}/users`.
-
-```ts
-await client.upsertAppUser({
-  externalUserId: "ext_abc123",
-  email: "dev@example.com",
-  status: "active",
-});
-```
-
-### `mintUserAccessToken({ externalUserId, scope })`
-
-Calls Builder API `POST /api/v1/apps/{clientId}/users/{externalUserId}/token`.
-
-```ts
-const userToken = await client.mintUserAccessToken({
-  externalUserId: "ext_abc123",
-  scope: "sign:job",
-});
-```
-
-### `completeDeviceApproval({ userJwt, userCode })`
-
-Completes NaaP Option B device approval via RFC 8693:
-
-`POST {issuer}/token` with `resource=urn:pmth:device_code:<user_code>`.
-
-```ts
-await client.completeDeviceApproval({
-  userJwt: userToken.access_token,
-  userCode: "ABCD-EFGH",
-});
-```
-
-### `exchangeForSignerSession({ userJwt })`
-
-Performs RFC 8693 gateway token exchange to obtain a `pmth_...` session token.
-
-```ts
-const signer = await client.exchangeForSignerSession({
-  userJwt: userToken.access_token,
-});
-```
-
-### `createSignerSessionToken({ userJwt })`
-
-Production-safe helper used by the website token endpoint:
-
-1. First attempts user-JWT exchange.
-2. Falls back to `client_credentials` + gateway exchange when server policy rejects user-JWT exchange for this client pairing.
-
-```ts
-const signer = await client.createSignerSessionToken({
-  userJwt: session.pmthUserJwt,
-});
-```
-
-### `getUsage({ startDate, endDate, groupBy, userId })`
-
-Calls Usage API with Basic auth and returns typed totals/by-user payload.
-
-```ts
-const usage = await client.getUsage({
-  startDate: "2026-01-01T00:00:00.000Z",
-  endDate: "2026-01-31T23:59:59.999Z",
-  groupBy: "user",
-});
-```
-
-## NaaP Option B Flow in Website
-
-The website follows this contract:
-
-1. Browser lands on `/api/auth/initiate-login` with `iss` and `target_link_uri`.
-2. Website validates issuer and target link.
-3. If user is not signed in, website stores a short-lived device-flow cookie and redirects to `/studio/login?flow=device`.
-4. On login, website:
-   - upserts app user,
-   - mints user JWT via Builder API,
-   - completes RFC 8693 device approval.
-5. Browser is redirected to `/studio/device-approved` while the CLI continues polling.
-
-## Error Taxonomy
-
-`PmtHouseError` includes:
-
-- `status`: HTTP status from the upstream failure surface
-- `code`: normalized machine code (for example, `invalid_client`, `invalid_scope`, `invalid_grant`, `invalid_target`)
-- `details`: original upstream response payload when available
-
-Use route handlers to pass through these fields without leaking secrets.
-
-## Security Boundaries
-
-- Keep `m2m` secret server-side only; never expose in client bundles.
-- Keep long-lived user JWTs in httpOnly signed session cookie (`lp_session`).
-- Use short-lived browser JWT (`lp_browser_jwt`) for browser-readable claims.
-- Validate `iss` and `target_link_uri` strictly for third-party initiate-login.
-- Normalize and validate RFC 8628 `user_code` before token exchange.
-
-## Key Design Decisions and Trade-offs
-
-1. **Framework-agnostic core client**: easier extraction into a standalone package later.
-2. **Discovery-first endpoints**: avoids hard-coded token endpoint drift.
-3. **Session metadata for token list**: no remote list/revoke API requirement; supports current UI quickly.
-4. **Gateway exchange fallback path**: maintains `pmth_` token UX even when user-JWT exchange is constrained by current server policy.
-5. **BigInt-safe fee handling**: wire `wei` as strings until render-time formatting.
-
-## Implementation Tasks
-
-- Confirm all required env vars are present in deployment targets.
-- Verify device flow end-to-end from `python-gateway` to `/studio/device-approved`.
-- Validate that `/api/tokens` emits real `pmth_` values in your environment.
-- Validate `/api/usage` values against known rows in PymtHouse for at least one date range.
-- Add persistent token metadata storage (DB) if cross-device visibility is required.
diff --git a/lib/pymthouse/client.ts b/lib/pymthouse/client.ts
deleted file mode 100644
index bef40ef..0000000
--- a/lib/pymthouse/client.ts
+++ /dev/null
@@ -1,351 +0,0 @@
-import { fetchDiscoveryDocument } from "@/lib/pymthouse/discovery";
-import { PmtHouseError } from "@/lib/pymthouse/errors";
-import type {
-  AppUserRecord,
-  ClientCredentialsTokenResponse,
-  DeviceApprovalInput,
-  FetchLike,
-  MintUserAccessTokenInput,
-  MintUserAccessTokenResponse,
-  OidcDiscoveryDocument,
-  ParsedDeviceApprovalRedirect,
-  PmtHouseClientOptions,
-  TokenExchangeResponse,
-  UpsertAppUserInput,
-  UsageApiResponse,
-  UsageQueryInput,
-} from "@/lib/pymthouse/types";
-
-const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
-const SUBJECT_ACCESS_TOKEN_TYPE =
-  "urn:ietf:params:oauth:token-type:access_token";
-const DEVICE_RESOURCE_PREFIX = "urn:pmth:device_code:";
-
-export class PmtHouseClient {
-  private readonly issuerUrl: string;
-  private readonly publicClientId: string;
-  private readonly m2mClientId: string;
-  private readonly m2mClientSecret: string;
-  private readonly fetchImpl: FetchLike;
-  private readonly logger?: PmtHouseClientOptions["logger"];
-
-  constructor(options: PmtHouseClientOptions) {
-    this.issuerUrl = options.issuerUrl.replace(/\/+$/, "");
-    this.publicClientId = options.publicClientId;
-    this.m2mClientId = options.m2mClientId;
-    this.m2mClientSecret = options.m2mClientSecret;
-    this.fetchImpl = options.fetch ?? fetch;
-    this.logger = options.logger;
-  }
-
-  async getDiscovery(): Promise<OidcDiscoveryDocument> {
-    return fetchDiscoveryDocument(this.issuerUrl, this.fetchImpl);
-  }
-
-  verifyIssuer(iss: string): boolean {
-    const candidate = iss.trim().replace(/\/+$/, "");
-    return candidate === this.issuerUrl;
-  }
-
-  parseDeviceApprovalRedirect(
-    searchParams: URLSearchParams,
-  ): ParsedDeviceApprovalRedirect {
-    const issuer = searchParams.get("iss")?.trim() ?? "";
-    const targetLinkUri = searchParams.get("target_link_uri")?.trim() ?? "";
-
-    if (!issuer || !targetLinkUri) {
-      throw new PmtHouseError("Missing iss or target_link_uri", {
-        status: 400,
-        code: "invalid_request",
-      });
-    }
-
-    if (!this.verifyIssuer(issuer)) {
-      throw new PmtHouseError("Issuer mismatch for initiate login", {
-        status: 400,
-        code: "invalid_issuer",
-      });
-    }
-
-    let targetUrl: URL;
-    try {
-      targetUrl = new URL(targetLinkUri);
-    } catch {
-      throw new PmtHouseError("target_link_uri is not a valid URL", {
-        status: 400,
-        code: "invalid_target",
-      });
-    }
-
-    const issuerOrigin = new URL(this.issuerUrl).origin;
-    if (targetUrl.origin !== issuerOrigin || targetUrl.pathname !== "/oidc/device") {
-      throw new PmtHouseError("target_link_uri does not point to the issuer device path", {
-        status: 400,
-        code: "invalid_target",
-      });
-    }
-
-    const userCode = this.normalizeUserCode(
-      targetUrl.searchParams.get("user_code") ?? "",
-    );
-    const clientId = targetUrl.searchParams.get("client_id")?.trim() ?? "";
-
-    if (!userCode || !clientId) {
-      throw new PmtHouseError("target_link_uri is missing user_code or client_id", {
-        status: 400,
-        code: "invalid_target",
-      });
-    }
-
-    return {
-      issuer,
-      targetLinkUri,
-      userCode,
-      clientId,
-    };
-  }
-
-  async listAppUsers(): Promise<{ users: AppUserRecord[] }> {
-    const url = `${this.getAppsBaseUrl()}/users`;
-    return this.requestJson<{ users: AppUserRecord[] }>(url, {
-      method: "GET",
-      headers: this.builderHeaders(),
-      cache: "no-store",
-    });
-  }
-
-  async upsertAppUser(input: UpsertAppUserInput): Promise<AppUserRecord> {
-    const payload: Record<string, unknown> = {
-      externalUserId: input.externalUserId,
-    };
-    if (input.email) payload.email = input.email;
-    if (input.status) payload.status = input.status;
-
-    const url = `${this.getAppsBaseUrl()}/users`;
-    return this.requestJson<AppUserRecord>(url, {
-      method: "POST",
-      headers: this.builderHeaders(),
-      body: JSON.stringify(payload),
-      cache: "no-store",
-    });
-  }
-
-  async deleteAppUser(params: { externalUserId: string }): Promise<{ success: boolean }> {
-    const url = new URL(`${this.getAppsBaseUrl()}/users`);
-    url.searchParams.set("externalUserId", params.externalUserId);
-    return this.requestJson<{ success: boolean }>(url.toString(), {
-      method: "DELETE",
-      headers: this.builderHeaders(),
-      cache: "no-store",
-    });
-  }
-
-  async mintUserAccessToken(
-    input: MintUserAccessTokenInput,
-  ): Promise<MintUserAccessTokenResponse> {
-    const url = `${this.getAppsBaseUrl()}/users/${encodeURIComponent(input.externalUserId)}/token`;
-    const body = input.scope ? { scope: input.scope } : {};
-
-    return this.requestJson<MintUserAccessTokenResponse>(url, {
-      method: "POST",
-      headers: this.builderHeaders(),
-      body: JSON.stringify(body),
-      cache: "no-store",
-    });
-  }
-
-  async completeDeviceApproval(
-    input: DeviceApprovalInput,
-  ): Promise<TokenExchangeResponse> {
-    const discovery = await this.getDiscovery();
-    const form = new URLSearchParams();
-    form.set("grant_type", TOKEN_EXCHANGE_GRANT);
-    form.set("subject_token", input.userJwt);
-    form.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE);
-    form.set(
-      "resource",
-      `${DEVICE_RESOURCE_PREFIX}${this.normalizeUserCode(input.userCode)}`,
-    );
-
-    return this.requestJson<TokenExchangeResponse>(discovery.token_endpoint, {
-      method: "POST",
-      headers: this.oidcFormHeaders(),
-      body: form.toString(),
-      cache: "no-store",
-    });
-  }
-
-  async issueMachineAccessToken(
-    scope = "sign:job",
-  ): Promise<ClientCredentialsTokenResponse> {
-    const discovery = await this.getDiscovery();
-    const form = new URLSearchParams();
-    form.set("grant_type", "client_credentials");
-    form.set("scope", scope);
-
-    return this.requestJson<ClientCredentialsTokenResponse>(discovery.token_endpoint, {
-      method: "POST",
-      headers: this.oidcFormHeaders(),
-      body: form.toString(),
-      cache: "no-store",
-    });
-  }
-
-  async exchangeForSignerSession(input: {
-    userJwt: string;
-  }): Promise<TokenExchangeResponse> {
-    const discovery = await this.getDiscovery();
-    const form = new URLSearchParams();
-    form.set("grant_type", TOKEN_EXCHANGE_GRANT);
-    form.set("subject_token", input.userJwt);
-    form.set("subject_token_type", SUBJECT_ACCESS_TOKEN_TYPE);
-    form.set("scope", "sign:job");
-
-    return this.requestJson<TokenExchangeResponse>(discovery.token_endpoint, {
-      method: "POST",
-      headers: this.oidcFormHeaders(),
-      body: form.toString(),
-      cache: "no-store",
-    });
-  }
-
-  async createSignerSessionToken(params: {
-    userJwt?: string;
-  }): Promise<TokenExchangeResponse> {
-    if (params.userJwt) {
-      try {
-        return await this.exchangeForSignerSession({ userJwt: params.userJwt });
-      } catch (error) {
-        const err = this.asError(error);
-        this.logger?.warn?.("User JWT exchange failed, falling back to machine exchange", {
-          code: err.code,
-          status: err.status,
-        });
-      }
-    }
-
-    const machineToken = await this.issueMachineAccessToken("sign:job");
-    if (!machineToken.access_token) {
-      throw new PmtHouseError("Client credentials flow did not return access_token", {
-        status: 502,
-        code: "invalid_token_response",
-      });
-    }
-
-    return this.exchangeForSignerSession({ userJwt: machineToken.access_token });
-  }
-
-  async getUsage(input: UsageQueryInput = {}): Promise<UsageApiResponse> {
-    const url = new URL(`${this.getAppsBaseUrl()}/usage`);
-    if (input.startDate) url.searchParams.set("startDate", input.startDate);
-    if (input.endDate) url.searchParams.set("endDate", input.endDate);
-    if (input.groupBy) url.searchParams.set("groupBy", input.groupBy);
-    if (input.userId) url.searchParams.set("userId", input.userId);
-
-    return this.requestJson<UsageApiResponse>(url.toString(), {
-      method: "GET",
-      headers: this.builderHeaders(),
-      cache: "no-store",
-    });
-  }
-
-  private normalizeUserCode(value: string): string {
-    return value
-      .replace(/[a-z]/g, (char) => char.toUpperCase())
-      .replace(/\W/g, "");
-  }
-
-  private getAppsBaseUrl(): string {
-    return `${this.getIssuerOrigin()}/api/v1/apps/${encodeURIComponent(this.publicClientId)}`;
-  }
-
-  private getIssuerOrigin(): string {
-    return new URL(this.issuerUrl).origin;
-  }
-
-  private builderHeaders(): HeadersInit {
-    return {
-      Authorization: this.basicAuthorizationHeader(),
-      "Content-Type": "application/json",
-      Accept: "application/json",
-    };
-  }
-
-  private oidcFormHeaders(): HeadersInit {
-    return {
-      Authorization: this.basicAuthorizationHeader(),
-      "Content-Type": "application/x-www-form-urlencoded",
-      Accept: "application/json",
-    };
-  }
-
-  private basicAuthorizationHeader(): string {
-    const raw = `${this.m2mClientId}:${this.m2mClientSecret}`;
-    return `Basic ${Buffer.from(raw).toString("base64")}`;
-  }
-
-  private async requestJson<T>(
-    url: string,
-    init: RequestInit,
-  ): Promise<T> {
-    this.logger?.debug?.("PmtHouse request", {
-      method: init.method ?? "GET",
-      url,
-    });
-
-    const response = await this.fetchImpl(url, init);
-    const raw = await response.text();
-    const parsed = raw ? this.safeParseJson(raw) : null;
-
-    if (!response.ok) {
-      const details = (parsed ?? {}) as Record<string, unknown>;
-      const description =
-        typeof details.error_description === "string"
-          ? details.error_description
-          : typeof details.error === "string"
-            ? details.error
-            : `Request failed (${response.status})`;
-
-      throw new PmtHouseError(description, {
-        status: response.status,
-        code:
-          typeof details.error === "string"
-            ? details.error
-            : "pymthouse_http_error",
-        details,
-      });
-    }
-
-    if (!parsed) {
-      return {} as T;
-    }
-
-    return parsed as T;
-  }
-
-  private safeParseJson(value: string): unknown {
-    try {
-      return JSON.parse(value);
-    } catch {
-      return null;
-    }
-  }
-
-  private asError(error: unknown): PmtHouseError {
-    if (error instanceof PmtHouseError) {
-      return error;
-    }
-
-    if (error instanceof Error) {
-      return new PmtHouseError(error.message, {
-        code: "unexpected_error",
-        status: 500,
-      });
-    }
-
-    return new PmtHouseError("Unexpected error", {
-      code: "unexpected_error",
-      status: 500,
-    });
-  }
-}
diff --git a/lib/pymthouse/discovery.ts b/lib/pymthouse/discovery.ts
deleted file mode 100644
index 1f0cfea..0000000
--- a/lib/pymthouse/discovery.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import type { FetchLike, OidcDiscoveryDocument } from "@/lib/pymthouse/types";
-import { PmtHouseError } from "@/lib/pymthouse/errors";
-
-const CACHE_TTL_MS = 5 * 60 * 1000;
-
-type CacheEntry = {
-  document: OidcDiscoveryDocument;
-  fetchedAt: number;
-};
-
-const discoveryCache = new Map<string, CacheEntry>();
-
-export async function fetchDiscoveryDocument(
-  issuerUrl: string,
-  fetchImpl: FetchLike,
-): Promise<OidcDiscoveryDocument> {
-  const normalizedIssuer = issuerUrl.replace(/\/+$/, "");
-  const cached = discoveryCache.get(normalizedIssuer);
-  const now = Date.now();
-
-  if (cached && now - cached.fetchedAt < CACHE_TTL_MS) {
-    return cached.document;
-  }
-
-  const discoveryUrl =
-    `${normalizedIssuer}/.well-known/openid-configuration`;
-
-  const response = await fetchImpl(discoveryUrl, {
-    method: "GET",
-    headers: {
-      Accept: "application/json",
-    },
-    cache: "no-store",
-  });
-
-  if (!response.ok) {
-    throw new PmtHouseError(
-      `Failed to load OIDC discovery (${response.status})`,
-      {
-        status: response.status,
-        code: "oidc_discovery_failed",
-      },
-    );
-  }
-
-  const payload = (await response.json()) as Partial<OidcDiscoveryDocument>;
-
-  if (!payload.issuer || !payload.token_endpoint || !payload.jwks_uri) {
-    throw new PmtHouseError("OIDC discovery document is missing fields", {
-      status: 500,
-      code: "oidc_discovery_invalid",
-      details: payload,
-    });
-  }
-
-  const document: OidcDiscoveryDocument = {
-    issuer: payload.issuer,
-    authorization_endpoint: payload.authorization_endpoint ?? "",
-    token_endpoint: payload.token_endpoint,
-    jwks_uri: payload.jwks_uri,
-    userinfo_endpoint: payload.userinfo_endpoint,
-    device_authorization_endpoint: payload.device_authorization_endpoint,
-  };
-
-  discoveryCache.set(normalizedIssuer, { document, fetchedAt: now });
-  return document;
-}
-
-export function clearDiscoveryCache(issuerUrl?: string): void {
-  if (!issuerUrl) {
-    discoveryCache.clear();
-    return;
-  }
-
-  discoveryCache.delete(issuerUrl.replace(/\/+$/, ""));
-}
diff --git a/lib/pymthouse/errors.ts b/lib/pymthouse/errors.ts
deleted file mode 100644
index 7d3e6b5..0000000
--- a/lib/pymthouse/errors.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-export class PmtHouseError extends Error {
-  readonly status: number;
-  readonly code: string;
-  readonly details?: unknown;
-
-  constructor(
-    message: string,
-    {
-      status = 500,
-      code = "pymthouse_error",
-      details,
-    }: {
-      status?: number;
-      code?: string;
-      details?: unknown;
-    } = {},
-  ) {
-    super(message);
-    this.name = "PmtHouseError";
-    this.status = status;
-    this.code = code;
-    this.details = details;
-  }
-}
-
-export function toPmtHouseError(
-  error: unknown,
-  fallbackMessage: string,
-): PmtHouseError {
-  if (error instanceof PmtHouseError) {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    return new PmtHouseError(error.message || fallbackMessage, {
-      code: "unexpected_error",
-      status: 500,
-    });
-  }
-
-  return new PmtHouseError(fallbackMessage, {
-    code: "unexpected_error",
-    status: 500,
-  });
-}
diff --git a/lib/pymthouse/format.ts b/lib/pymthouse/format.ts
deleted file mode 100644
index efd0966..0000000
--- a/lib/pymthouse/format.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-const WEI_PER_ETH = BigInt("1000000000000000000");
-
-export function formatWeiToEth(wei: string): string {
-  const weiValue = BigInt(wei || "0");
-  const whole = weiValue / WEI_PER_ETH;
-  const fraction = weiValue % WEI_PER_ETH;
-  const fractionStr = fraction.toString().padStart(18, "0").slice(0, 6);
-  if (fractionStr === "000000") {
-    return `${whole.toString()} ETH`;
-  }
-  return `${whole.toString()}.${fractionStr} ETH`;
-}
-
-export function formatWeiToUsd(
-  wei: string,
-  usdPerEth = 3500,
-): string {
-  const weiValue = BigInt(wei || "0");
-  const whole = weiValue / WEI_PER_ETH;
-  const fraction = weiValue % WEI_PER_ETH;
-  const eth = Number(whole) + Number(fraction) / 1e18;
-  const usd = eth * usdPerEth;
-  return `$${usd.toFixed(2)}`;
-}
diff --git a/lib/pymthouse/index.ts b/lib/pymthouse/index.ts
deleted file mode 100644
index 8d8bc12..0000000
--- a/lib/pymthouse/index.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-export { PmtHouseClient } from "@/lib/pymthouse/client";
-export { PmtHouseError, toPmtHouseError } from "@/lib/pymthouse/errors";
-export { formatWeiToEth, formatWeiToUsd } from "@/lib/pymthouse/format";
-export { getPmtHouseClient } from "@/lib/pymthouse/server";
-export type {
-  AppUserRecord,
-  ClientCredentialsTokenResponse,
-  DeviceApprovalInput,
-  MintUserAccessTokenInput,
-  MintUserAccessTokenResponse,
-  OidcDiscoveryDocument,
-  ParsedDeviceApprovalRedirect,
-  PmtHouseClientOptions,
-  TokenExchangeResponse,
-  UpsertAppUserInput,
-  UsageApiResponse,
-  UsageByUserRow,
-  UsageQueryInput,
-  UsageTotals,
-} from "@/lib/pymthouse/types";
diff --git a/lib/pymthouse/server.ts b/lib/pymthouse/server.ts
deleted file mode 100644
index fb7b0a5..0000000
--- a/lib/pymthouse/server.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { PmtHouseClient } from "@/lib/pymthouse/client";
-import { PmtHouseError } from "@/lib/pymthouse/errors";
-
-let cachedClient: PmtHouseClient | null = null;
-
-function requiredEnv(name: string): string {
-  const value = process.env[name];
-  if (value && value.trim()) {
-    return value.trim();
-  }
-
-  throw new PmtHouseError(`Missing required environment variable: ${name}`, {
-    status: 500,
-    code: "missing_env",
-  });
-}
-
-export function getPmtHouseClient(): PmtHouseClient {
-  if (cachedClient) {
-    return cachedClient;
-  }
-
-  cachedClient = new PmtHouseClient({
-    issuerUrl: requiredEnv("PYMTHOUSE_ISSUER_URL"),
-    publicClientId: requiredEnv("PYMTHOUSE_PUBLIC_CLIENT_ID"),
-    m2mClientId: requiredEnv("PYMTHOUSE_M2M_CLIENT_ID"),
-    m2mClientSecret: requiredEnv("PYMTHOUSE_M2M_CLIENT_SECRET"),
-    logger: {
-      debug: (message, details) => {
-        if (process.env.NODE_ENV !== "production") {
-          console.debug(`[pymthouse] ${message}`, details ?? {});
-        }
-      },
-      warn: (message, details) => {
-        console.warn(`[pymthouse] ${message}`, details ?? {});
-      },
-    },
-  });
-
-  return cachedClient;
-}
diff --git a/lib/pymthouse/types.ts b/lib/pymthouse/types.ts
deleted file mode 100644
index 33d8ffd..0000000
--- a/lib/pymthouse/types.ts
+++ /dev/null
@@ -1,115 +0,0 @@
-export type FetchLike = (
-  input: string | URL | Request,
-  init?: RequestInit,
-) => Promise<Response>;
-
-export interface OidcDiscoveryDocument {
-  issuer: string;
-  authorization_endpoint: string;
-  token_endpoint: string;
-  jwks_uri: string;
-  userinfo_endpoint?: string;
-  device_authorization_endpoint?: string;
-}
-
-export interface PmtHouseClientOptions {
-  issuerUrl: string;
-  publicClientId: string;
-  m2mClientId: string;
-  m2mClientSecret: string;
-  fetch?: FetchLike;
-  logger?: {
-    debug?: (message: string, details?: Record<string, unknown>) => void;
-    warn?: (message: string, details?: Record<string, unknown>) => void;
-  };
-}
-
-export interface UpsertAppUserInput {
-  externalUserId: string;
-  email?: string;
-  status?: "active" | "inactive";
-}
-
-export interface AppUserRecord {
-  id: string;
-  clientId: string;
-  externalUserId: string;
-  email: string | null;
-  status: string;
-  role: string;
-  createdAt: string;
-}
-
-export interface MintUserAccessTokenInput {
-  externalUserId: string;
-  scope?: string;
-}
-
-export interface MintUserAccessTokenResponse {
-  access_token: string;
-  refresh_token: string;
-  token_type: "Bearer";
-  expires_in: number;
-  scope: string;
-  subject_type: "app_user";
-  correlation_id?: string;
-}
-
-export interface DeviceApprovalInput {
-  userJwt: string;
-  userCode: string;
-}
-
-export interface TokenExchangeResponse {
-  access_token: string;
-  token_type: "Bearer";
-  expires_in: number;
-  scope: string;
-  issued_token_type: string;
-}
-
-export interface UsageQueryInput {
-  startDate?: string;
-  endDate?: string;
-  groupBy?: "none" | "user";
-  userId?: string;
-}
-
-export interface UsageTotals {
-  requestCount: number;
-  totalFeeWei: string;
-}
-
-export interface UsageByUserRow {
-  endUserId: string;
-  externalUserId: string | null;
-  requestCount: number;
-  feeWei: string;
-  userType?: "system_managed" | "oidc_authorized" | "unknown";
-  identifier?: string;
-}
-
-export interface UsageApiResponse {
-  clientId: string;
-  period: {
-    start: string | null;
-    end: string | null;
-  };
-  totals: UsageTotals;
-  byUser?: UsageByUserRow[];
-}
-
-export interface ClientCredentialsTokenResponse {
-  access_token: string;
-  token_type: "Bearer";
-  expires_in?: number;
-  scope?: string;
-  [key: string]: unknown;
-}
-
-export interface ParsedDeviceApprovalRedirect {
-  issuer: string;
-  targetLinkUri: string;
-  userCode: string;
-  clientId: string;
-}
diff --git a/package.json b/package.json
index dfae896..56fdfb0 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
+    "@pymthouse/builder-api": "^0.0.4",
     "framer-motion": "^11.15.0",
     "gray-matter": "^4.0.3",
     "jose": "^6.2.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index be71e63..0bc8581 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      '@pymthouse/builder-api':
+        specifier: ^0.0.4
+        version: 0.0.4
       framer-motion:
         specifier: ^11.15.0
         version: 11.18.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -403,6 +406,10 @@ packages:
     resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
     engines: {node: '>=12.4.0'}
 
+  '@pymthouse/builder-api@0.0.4':
+    resolution: {integrity: sha512-24ZDRtIcs2QryJndQW8Y2ELlgAI3wCtSdHyv/d3jk+FBIUil9WozeX6gwOp6Od+pm7u4gT2OF/RqhMDUlnyYHw==}
+    engines: {node: '>=20'}
+
   '@reduxjs/toolkit@2.11.2':
     resolution: {integrity: sha512-Kd6kAHTA6/nUpp8mySPqj3en3dm0tdMIgbttnQ1xFMVpufoj+ADi8pXLBsd4xzTRHQa7t/Jv8W5UnCuW4kuWMQ==}
     peerDependencies:
@@ -1819,6 +1826,9 @@ packages:
     resolution: {integrity: sha512-pyFS63ptit/P5WqUkt+UUfe+4oevH+bFeIiPPdfb0pFeYEu/1ELnJu5l+5EcTKYL5M7zaAa7S8ddywgXypqKCw==}
     engines: {node: '>= 0.4'}
 
+  oauth4webapi@3.8.5:
+    resolution: {integrity: sha512-A8jmyUckVhRJj5lspguklcl90Ydqk61H3dcU0oLhH3Yv13KpAliKTt5hknpGGPZSSfOwGyraNEFmofDYH+1kSg==}
+
   object-assign@4.1.1:
     resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
     engines: {node: '>=0.10.0'}
@@ -2541,6 +2551,10 @@ snapshots:
 
   '@nolyfill/is-core-module@1.0.39': {}
 
+  '@pymthouse/builder-api@0.0.4':
+    dependencies:
+      oauth4webapi: 3.8.5
+
   '@reduxjs/toolkit@2.11.2(react-redux@9.2.0(@types/react@19.2.14)(react@19.2.4)(redux@5.0.1))(react@19.2.4)':
     dependencies:
       '@standard-schema/spec': 1.1.0
@@ -4141,6 +4155,8 @@ snapshots:
       object.entries: 1.1.9
       semver: 6.3.1
 
+  oauth4webapi@3.8.5: {}
+
   object-assign@4.1.1: {}
 
   object-inspect@1.13.4: {}

From 1726e2448f0ac38103f181e33e7aa54372d32069 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Sun, 19 Apr 2026 23:38:18 -0400
Subject: [PATCH 4/5] feat: enhance login flow with device flow handling and
 loading states

Refactored the login page to support device flow authentication, introducing a new `DeviceFlowLoadingScreen` component for improved user experience during device login. Updated the `LoginRoute` to conditionally render based on connection status and device flow parameters. Added loading indicators to enhance feedback during authentication processes.
---
 app/(studio-auth)/studio/login/page.tsx       | 46 ++++++++++++++++---
 components/studio/DeviceFlowLoadingScreen.tsx | 46 +++++++++++++++++++
 components/studio/LoginPage.tsx               |  5 ++
 3 files changed, 91 insertions(+), 6 deletions(-)
 create mode 100644 components/studio/DeviceFlowLoadingScreen.tsx

diff --git a/app/(studio-auth)/studio/login/page.tsx b/app/(studio-auth)/studio/login/page.tsx
index 3d97e62..e06476c 100644
--- a/app/(studio-auth)/studio/login/page.tsx
+++ b/app/(studio-auth)/studio/login/page.tsx
@@ -1,21 +1,55 @@
 "use client";
 
-import { useEffect } from "react";
-import { useRouter } from "next/navigation";
+import { Suspense, useEffect } from "react";
+import { useRouter, useSearchParams } from "next/navigation";
 import { useAuth } from "@/components/studio/AuthContext";
 import LoginPage from "@/components/studio/LoginPage";
 
-export default function LoginRoute() {
+function LoginRouteInner() {
   const { isConnected, isLoading } = useAuth();
   const router = useRouter();
+  const searchParams = useSearchParams();
+  const deviceFlow = searchParams.get("flow") === "device";
 
   useEffect(() => {
-    if (!isLoading && isConnected) {
+    if (!isLoading && isConnected && !deviceFlow) {
       router.replace("/studio");
     }
-  }, [isConnected, isLoading, router]);
+  }, [isConnected, isLoading, deviceFlow, router]);
+
+  if (isLoading) {
+    return (
+      <div className="flex min-h-screen items-center justify-center bg-dark">
+        <div
+          className="h-9 w-9 animate-spin rounded-full border-2 border-white/10 border-t-green-bright"
+          role="status"
+          aria-label="Checking session"
+        />
+      </div>
+    );
+  }
 
-  if (isLoading || isConnected) return null;
+  if (isConnected && !deviceFlow) {
+    return null;
+  }
 
   return <LoginPage />;
 }
+
+export default function LoginRoute() {
+  return (
+    <Suspense
+      fallback={
+        <div className="flex min-h-screen items-center justify-center bg-dark">
+          <div
+            className="h-9 w-9 animate-spin rounded-full border-2 border-white/10 border-t-green-bright"
+            role="status"
+            aria-label="Loading"
+          />
+        </div>
+      }
+    >
+      <LoginRouteInner />
+    </Suspense>
+  );
+}
diff --git a/components/studio/DeviceFlowLoadingScreen.tsx b/components/studio/DeviceFlowLoadingScreen.tsx
new file mode 100644
index 0000000..8170527
--- /dev/null
+++ b/components/studio/DeviceFlowLoadingScreen.tsx
@@ -0,0 +1,46 @@
+import { LivepeerSymbol } from "@/components/icons/LivepeerLogo";
+
+/**
+ * Full-screen loading state for RFC 8628 / third-party device login — matches
+ * `/studio/device-approved` so users stay oriented (no dashboard flash).
+ */
+export default function DeviceFlowLoadingScreen() {
+  return (
+    <main className="relative flex min-h-screen items-center justify-center overflow-hidden bg-dark px-6">
+      <div
+        className="pointer-events-none absolute inset-0"
+        style={{
+          background:
+            "radial-gradient(ellipse 60% 50% at 50% 45%, rgba(24,121,78,0.10) 0%, rgba(24,121,78,0.03) 45%, transparent 70%)",
+        }}
+        aria-hidden="true"
+      />
+      <div
+        className="pointer-events-none absolute inset-0"
+        style={{
+          background:
+            "radial-gradient(ellipse 75% 70% at 50% 48%, transparent 40%, rgba(18,18,18,0.5) 70%, rgba(18,18,18,0.85) 100%)",
+        }}
+        aria-hidden="true"
+      />
+      <div className="relative z-10 w-full max-w-md rounded-2xl border border-white/10 bg-white/[0.03] p-8 text-center">
+        <div className="mb-5 flex justify-center">
+          <LivepeerSymbol className="h-9 w-9 text-white" />
+        </div>
+        <h1 className="text-2xl font-medium tracking-tight text-white">
+          Approving device login
+        </h1>
+        <p className="mt-3 text-sm leading-relaxed text-white/60">
+          Stay on this page while we finish connecting your terminal. This
+          usually takes a few seconds.
+        </p>
+        <div className="mt-8 flex justify-center" role="status" aria-live="polite">
+          <div
+            className="h-9 w-9 animate-spin rounded-full border-2 border-white/15 border-t-green-bright"
+            aria-hidden
+          />
+        </div>
+      </div>
+    </main>
+  );
+}
diff --git a/components/studio/LoginPage.tsx b/components/studio/LoginPage.tsx
index 9c9ddc1..10ada18 100644
--- a/components/studio/LoginPage.tsx
+++ b/components/studio/LoginPage.tsx
@@ -5,6 +5,7 @@ import { useRouter, useSearchParams } from "next/navigation";
 import { motion, AnimatePresence } from "framer-motion";
 import { useAuth, type AuthProvider } from "@/components/studio/AuthContext";
 import { LivepeerSymbol } from "@/components/icons/LivepeerLogo";
+import DeviceFlowLoadingScreen from "@/components/studio/DeviceFlowLoadingScreen";
 
 function GitHubIcon({ className }: { className?: string }) {
   return (
@@ -137,6 +138,10 @@ export default function LoginPage() {
     void submitLogin({ provider });
   }
 
+  if (deviceFlow && isSubmitting) {
+    return <DeviceFlowLoadingScreen />;
+  }
+
   return (
     <div className="relative flex min-h-screen items-center justify-center overflow-hidden">
       {/* ─── Layer 1: dark base ─── */}

From 0a77b58af941816f9af19222f782250f6f32b377 Mon Sep 17 00:00:00 2001
From: John | Elite Encoder <john@eliteencoder.net>
Date: Mon, 20 Apr 2026 21:12:34 -0400
Subject: [PATCH 5/5] feat: refactor UsageTab component to improve data
 handling and loading states

Updated the UsageTab component to utilize a new `normalizeUsagePayload` function for better data management. Refactored state handling for usage data, ensuring default values are set correctly. Enhanced loading indicators and conditional rendering for improved user experience during data fetching. Removed unused mock data imports and streamlined the code for clarity.
---
 components/studio/settings/UsageTab.tsx | 110 +++++++++++++++---------
 1 file changed, 70 insertions(+), 40 deletions(-)

diff --git a/components/studio/settings/UsageTab.tsx b/components/studio/settings/UsageTab.tsx
index ab2946f..4591219 100644
--- a/components/studio/settings/UsageTab.tsx
+++ b/components/studio/settings/UsageTab.tsx
@@ -14,21 +14,43 @@ import { ChevronDown } from "lucide-react";
 import StatCard from "@/components/studio/statistics/StatCard";
 import PeriodToggle from "@/components/studio/statistics/PeriodToggle";
 import { StackedChartTooltip } from "@/components/studio/statistics/ChartTooltip";
-import {
-  ACCOUNT_USAGE_SUMMARY,
-  ACCOUNT_USAGE_BY_SIGNER,
-  ACCOUNT_USAGE_BY_TOKEN,
-  ACCOUNT_USAGE_DAILY,
-  MOCK_RECENT_REQUESTS,
-  SIGNER_COLORS,
-} from "@/lib/studio/mock-data";
+import { SIGNER_COLORS } from "@/lib/studio/mock-data";
 import type {
   NetworkStat,
   AccountActivityRow,
+  AccountUsageBySigner,
+  AccountUsageByToken,
   AccountUsageDailyPoint,
+  AccountUsageSummary,
   SignerKey,
 } from "@/lib/studio/types";
 
+type UsagePayload = {
+  summary: AccountUsageSummary;
+  bySigner: AccountUsageBySigner[];
+  byToken: AccountUsageByToken[];
+  daily: AccountUsageDailyPoint[];
+  recentRequests: AccountActivityRow[];
+};
+
+function normalizeUsagePayload(
+  payload: Partial<UsagePayload> & { recentRequests?: AccountActivityRow[] },
+): UsagePayload {
+  return {
+    summary: payload.summary ?? {
+      requests: 0,
+      spendDisplay: "$0.00",
+      freeTierUsed: 0,
+      freeTierLimit: 10_000,
+      freeTierResetIn: "—",
+    },
+    bySigner: payload.bySigner ?? [],
+    byToken: payload.byToken ?? [],
+    daily: payload.daily ?? [],
+    recentRequests: payload.recentRequests ?? [],
+  };
+}
+
 // ─── Period filter ───
 
 type Period = "24h" | "7d" | "30d" | "3m";
@@ -128,14 +150,9 @@ export default function UsageTab() {
   const [period, setPeriod] = useState<Period>("30d");
   const [signerFilter, setSignerFilter] = useState<SignerFilter>("all");
   const [tokenFilter, setTokenFilter] = useState<string>("all");
-  const [usageLoading, setUsageLoading] = useState(false);
+  const [usageLoading, setUsageLoading] = useState(true);
   const [usageError, setUsageError] = useState<string | null>(null);
-  const [usageData, setUsageData] = useState<{
-    summary: typeof ACCOUNT_USAGE_SUMMARY;
-    bySigner: typeof ACCOUNT_USAGE_BY_SIGNER;
-    byToken: typeof ACCOUNT_USAGE_BY_TOKEN;
-    daily: typeof ACCOUNT_USAGE_DAILY;
-  } | null>(null);
+  const [usageData, setUsageData] = useState<UsagePayload | null>(null);
   const [highlightedRequestId, setHighlightedRequestId] = useState<
     string | null
   >(null);
@@ -152,23 +169,14 @@ export default function UsageTab() {
           method: "GET",
           cache: "no-store",
         });
-        const payload = (await response.json().catch(() => ({}))) as {
-          summary?: typeof ACCOUNT_USAGE_SUMMARY;
-          bySigner?: typeof ACCOUNT_USAGE_BY_SIGNER;
-          byToken?: typeof ACCOUNT_USAGE_BY_TOKEN;
-          daily?: typeof ACCOUNT_USAGE_DAILY;
+        const payload = (await response.json().catch(() => ({}))) as Partial<UsagePayload> & {
           error_description?: string;
         };
         if (!response.ok) {
           throw new Error(payload.error_description || "Failed to load usage data.");
         }
         if (!cancelled) {
-          setUsageData({
-            summary: payload.summary ?? ACCOUNT_USAGE_SUMMARY,
-            bySigner: payload.bySigner ?? ACCOUNT_USAGE_BY_SIGNER,
-            byToken: payload.byToken ?? ACCOUNT_USAGE_BY_TOKEN,
-            daily: payload.daily ?? ACCOUNT_USAGE_DAILY,
-          });
+          setUsageData(normalizeUsagePayload(payload));
         }
       } catch (error) {
         if (!cancelled) {
@@ -190,10 +198,10 @@ export default function UsageTab() {
     };
   }, [period]);
 
-  const summary = usageData?.summary ?? ACCOUNT_USAGE_SUMMARY;
-  const signerRows = usageData?.bySigner ?? ACCOUNT_USAGE_BY_SIGNER;
-  const tokenRows = usageData?.byToken ?? ACCOUNT_USAGE_BY_TOKEN;
-  const dailyRows = usageData?.daily ?? ACCOUNT_USAGE_DAILY;
+  const summary = usageData?.summary;
+  const signerRows = usageData?.bySigner ?? [];
+  const tokenRows = usageData?.byToken ?? [];
+  const dailyRows = usageData?.daily ?? [];
 
   const chartData = useMemo(
     () => filterByPeriod(dailyRows, period),
@@ -239,14 +247,15 @@ export default function UsageTab() {
   }, [period]);
 
   const filteredActivity = useMemo<AccountActivityRow[]>(() => {
-    return MOCK_RECENT_REQUESTS.filter((row) => {
+    const rows = usageData?.recentRequests ?? [];
+    return rows.filter((row) => {
       const ts = new Date(row.timestamp).getTime();
       if (Number.isNaN(ts) || ts < periodCutoffMs) return false;
       if (signerFilter !== "all" && row.signer !== signerFilter) return false;
       if (tokenFilter !== "all" && row.tokenId !== tokenFilter) return false;
       return true;
     });
-  }, [periodCutoffMs, signerFilter, tokenFilter]);
+  }, [usageData?.recentRequests, periodCutoffMs, signerFilter, tokenFilter]);
 
   const clearAllFilters = () => {
     setPeriod("30d");
@@ -287,23 +296,20 @@ export default function UsageTab() {
   }, [targetRequestId, filteredActivity]);
 
   const headerStats: NetworkStat[] = useMemo(() => {
+    if (!summary) return [];
     const freePct = Math.round(
-      (summary.freeTierUsed /
-        summary.freeTierLimit) *
-        100,
+      (summary.freeTierUsed / summary.freeTierLimit) * 100,
     );
     return [
       {
         label: "Requests this period",
         value: summary.requests.toLocaleString(),
-        delta: "+12.4% vs last period",
-        trend: "up",
+        trend: "flat",
       },
       {
         label: "Spend this period",
         value: summary.spendDisplay,
-        delta: "+8.1% vs last period",
-        trend: "up",
+        trend: "flat",
       },
       {
         label: `Free tier (${freePct}% used)`,
@@ -333,6 +339,8 @@ export default function UsageTab() {
     [tokenRows],
   );
 
+  const showSyncBanner = usageLoading && usageData;
+
   return (
     <div className="px-6 pt-6 pb-10">
       {usageError && (
@@ -341,12 +349,32 @@ export default function UsageTab() {
         </div>
       )}
 
-      {usageLoading && (
+      {usageLoading && !usageData && (
+        <div className="space-y-6" aria-busy="true" aria-label="Loading usage">
+          <p className="text-center text-xs text-white/50">Loading usage…</p>
+          <div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
+            {[0, 1, 2].map((i) => (
+              <div
+                key={i}
+                className="h-[88px] animate-pulse rounded-xl border border-white/[0.06] bg-white/[0.04]"
+              />
+            ))}
+          </div>
+          <div className="h-[380px] animate-pulse rounded-xl border border-white/[0.06] bg-white/[0.04]" />
+          <div className="h-[200px] animate-pulse rounded-xl border border-white/[0.06] bg-white/[0.04]" />
+          <div className="h-[200px] animate-pulse rounded-xl border border-white/[0.06] bg-white/[0.04]" />
+          <div className="h-[240px] animate-pulse rounded-xl border border-white/[0.06] bg-white/[0.04]" />
+        </div>
+      )}
+
+      {showSyncBanner && (
         <div className="mb-4 rounded-lg border border-white/[0.08] bg-white/[0.02] px-4 py-3 text-xs text-white/50">
           Syncing usage from pymthouse...
         </div>
       )}
 
+      {usageData && (
+        <>
       {/* KPI cards */}
       <div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
         {headerStats.map((stat) => (
@@ -743,6 +771,8 @@ export default function UsageTab() {
           </div>
         )}
       </div>
+        </>
+      )}
     </div>
   );
 }