Builder SDK

@pymthouse/builder-sdk is the official TypeScript/npm SDK for PymtHouse app builders. It wraps:

Confidential Builder and Usage REST APIs (M2M auth, user provisioning, billing)
OIDC protocol flows (token mint, exchange, device login, JWT verify) via oauth4webapi
Signer integration (direct DMZ proxy and identity webhook for go-livepeer)
Client-safe utilities (config checks, device-initiate validation, formatting, plan pricing math)

Install

pnpm add @pymthouse/builder-sdk
# or
npm install @pymthouse/builder-sdk

Node ≥ 20 required.

Quick start

From environment variables (recommended for server use)

import { createPmtHouseClientFromEnv } from "@pymthouse/builder-sdk/env";

const client = createPmtHouseClientFromEnv();
const discovery = await client.getDiscovery();

Explicit construction

import { PmtHouseClient } from "@pymthouse/builder-sdk";

const client = new PmtHouseClient({
  issuerUrl: process.env.PYMTHOUSE_ISSUER_URL!,
  publicClientId: process.env.PYMTHOUSE_PUBLIC_CLIENT_ID!,
  m2mClientId: process.env.PYMTHOUSE_M2M_CLIENT_ID!,
  m2mClientSecret: process.env.PYMTHOUSE_M2M_CLIENT_SECRET!,
});

Environment variables

The env subpath reads these variables. Set them in your backend environment or secret manager.

Variable	Value	Notes
`PYMTHOUSE_ISSUER_URL`	`https://pymthouse.com/api/v1/oidc`	Must match `iss` in issued tokens.
`PYMTHOUSE_PUBLIC_CLIENT_ID`	`app_…`	Public OIDC client id. Used in device/browser flows and JWT claims.
`PYMTHOUSE_M2M_CLIENT_ID`	`m2m_…`	Confidential M2M client id. Server-side only.
`PYMTHOUSE_M2M_CLIENT_SECRET`	`pmth_cs_…`	M2M client secret. Server-side only. Rotate via the credentials endpoint.

The @pymthouse/builder-sdk/env subpath throws immediately if imported in a browser context (detects globalThis.window). In Next.js, add import "server-only" in any file that re-exports createPmtHouseClientFromEnv to enforce the server-only constraint at build time.

`PmtHouseClient` method reference

All REST calls use HTTP Basic auth against {issuerOrigin}/api/v1/apps/{publicClientId}/….

Discovery & OIDC

Method	Description
`getDiscovery()`	Fetch OIDC discovery document (5-min cache).
`verifyIssuer(iss)`	Validate an issuer URL against this client’s issuer.
`issueMachineAccessToken(scope?)`	Client credentials grant; returns a machine access token.

User management

Method	Description
`listAppUsers()`	`GET .../users` — list provisioned users. Requires `users:read`.
`upsertAppUser(input)`	`POST .../users` — create or update a user. Requires `users:write`.
`deleteAppUser({ externalUserId })`	`DELETE .../users` — deactivate a user.

Token minting & exchange

Method	Description
`mintUserAccessToken(input)`	`POST .../users/{id}/token` — short-lived JWT. `scope` defaults to `sign:job`. Requires `users:token`. Throws `PmtHouseError({ status: 404, code: "not_found" })` if the user has not been provisioned.
`ensureUserAndMintToken(input)`	Same as `mintUserAccessToken` but auto-provisions the user on `404 / not_found` via `upsertAppUser` + retry. Use this for lazy provisioning instead of calling the two methods manually.
`exchangeForSignerSession({ userJwt, resource? })`	RFC 8693: user JWT → opaque `pmth_*` signer session.
`mintUserSignerSessionToken(input)`	Mint user JWT + exchange in one call.
`mintSignerSessionForExternalUser(input)`	Eager upsert + mint + exchange in one call. Always upserts the user first; use `ensureUserAndMintToken` when you only need a JWT without the signer exchange.
`createSignerSessionToken({ userJwt? })`	Exchange or fall back to machine token.
`exchangeApiKeyForUserAccessToken({ apiKey })`	`POST .../auth/api-key/token` — API key → short-lived JWT.
`exchangeApiKeyForSignerSession({ apiKey, facadeUrl? })`	API key → opaque signer session.

Device flow

Method	Description
`parseDeviceApprovalRedirect(searchParams)`	Parse initiate-login redirect parameters.
`completeDeviceApproval({ userJwt, userCode })`	RFC 8693 token exchange to bind a device grant.
`approveDeviceLogin(input)`	Full Option B device approval workflow.

Usage & billing

Method	Description
`getUsage(input?)`	`GET .../usage` with groupBy/retail filters.
`fetchUsageForExternalUser(input)`	BFF-style `scope=me` usage rollup for a single user.
`getUsageBalance(externalUserId)`	`GET .../usage/balance` — entitlement balance.
`getUserAllowances(externalUserId)`	`GET .../users/{id}/allowances`.
`grantUserAllowance(externalUserId, input)`	`POST .../users/{id}/allowances`.
`getUserSubscription(externalUserId)`	`GET .../users/{id}/subscription`.
`listBillingProducts()`	`GET .../plans?apiVersion=2` — returns `BillingProduct[]`.
`syncBillingProduct(planId)`	`POST .../plans/{id}/sync` — explicit OpenMeter sync.

Signer routing

Method	Description
`getSignerRouting()`	`GET .../signer/routing` — DMZ URL, webhook URL, metering mode.

Subpath exports

Import	Runtime safety	Purpose
`@pymthouse/builder-sdk`	Node + Edge	`PmtHouseClient`, usage helpers, manifest parsers, token helpers, error types
`@pymthouse/builder-sdk/env`	Node only (throws in browser)	`createPmtHouseClientFromEnv`, `getPymthouseBaseUrl`
`@pymthouse/builder-sdk/config`	Edge-safe	`isPymthouseConfigured`, `readPymthouseEnv`, URL helpers
`@pymthouse/builder-sdk/tokens`	Edge-safe	Signer session TTL constants, JWT shape helpers, `parseSignerSessionExchange`
`@pymthouse/builder-sdk/device`	Node + Edge	`pollDeviceToken` — RFC 8628 device code polling
`@pymthouse/builder-sdk/device-initiate`	Edge-safe	`validateDeviceInitiateLogin`, `extractDeviceApprovalFromTargetLink`
`@pymthouse/builder-sdk/verify`	Node + Edge	`verifyJwt` — RFC 9068 JWT validation via JWKS
`@pymthouse/builder-sdk/format`	Edge-safe	`formatWeiToEth`, `formatWeiToUsd` — wei display formatting
`@pymthouse/builder-sdk/plan-pricing`	Edge-safe	`markupPercentToRetailRateUsd`, `applyRetailRateToNetworkMicros`, plan pricing math
`@pymthouse/builder-sdk/signer/server`	Node only	`mintUserSignerToken`, `createSignerTokenManager`, `createDirectSignerProxyHandler`, `forwardDirectSignerRequest`
`@pymthouse/clearinghouse-identity-webhook`	Node	Root re-export of all subpaths below
`@pymthouse/clearinghouse-identity-webhook/protocol`	Node	`handleAuthorize` — go-livepeer identity webhook handler
`@pymthouse/clearinghouse-identity-webhook/verifiers`	Node	`createOidcVerifier`, `createApiKeyVerifier`, `createEndUserVerifierFromEnv`, `splitCompositeApiKey`
`@pymthouse/clearinghouse-identity-webhook/balance-gate`	Node	`createBalanceGate` — live balance check inside the identity webhook

Common usage patterns

Construct the client

// Explicit constructor (recommended — handles all env vars including PYMTHOUSE_ALLOW_INSECURE_HTTP)
import { PmtHouseClient } from "@pymthouse/builder-sdk";

const client = new PmtHouseClient({
  issuerUrl: process.env.PYMTHOUSE_ISSUER_URL!,
  publicClientId: process.env.PYMTHOUSE_PUBLIC_CLIENT_ID!,
  m2mClientId: process.env.PYMTHOUSE_M2M_CLIENT_ID!,
  m2mClientSecret: process.env.PYMTHOUSE_M2M_CLIENT_SECRET!,
  allowInsecureHttp: process.env.PYMTHOUSE_ALLOW_INSECURE_HTTP === "1",
});

// Convenience factory — reads the same env vars automatically.
// allowInsecureHttp is inferred from http: issuer URL or PYMTHOUSE_ALLOW_INSECURE_HTTP=1.
import { createPmtHouseClientFromEnv } from "@pymthouse/builder-sdk/env";
const client = createPmtHouseClientFromEnv();

Mint a user JWT (lazy provisioning)

// ensureUserAndMintToken — auto-provisions on 404, no eager upsert needed
const { access_token } = await client.ensureUserAndMintToken({
  externalUserId: "user-123",
  // scope defaults to "sign:job" when omitted
});

// mintUserAccessToken — throws PmtHouseError({ status: 404, code: "not_found" })
// if the user hasn't been provisioned yet. Use when you provision eagerly on sign-up.
const { access_token } = await client.mintUserAccessToken({
  externalUserId: "user-123",
});

Mint a signer session for the DMZ

// mintSignerSessionForExternalUser — eager upsert + mint + RFC 8693 exchange in one call
// Returns SignerSessionToken (opaque pmth_* bearer)
const session = await client.mintSignerSessionForExternalUser({
  externalUserId: "user-123",
});
// session.access_token — opaque pmth_… bearer for the remote signer DMZ

// mintUserSignerToken (from signer/server) — M2M client_credentials mint returning
// CachedSignerToken with jwt, balanceUsdMicros, lifetimeGrantedUsdMicros, expiresAt.
// Use createSignerTokenManager for TTL caching across requests (recommended for production).
import { mintUserSignerToken, createSignerTokenManager } from "@pymthouse/builder-sdk/signer/server";

Check usage balance before signing

const balance = await client.getUsageBalance("naap-user-123");
if (!balance.hasAccess) {
  throw new Error("Insufficient balance");
}

await client.approveDeviceLogin({
  externalUserId: "naap-user-123",
  userCode: "ABCD-EFGH",
  publicClientId: process.env.PYMTHOUSE_PUBLIC_CLIENT_ID,
});

Usage BFF rollup

import { summarizeUsageForExternalUser } from "@pymthouse/builder-sdk";

const usage = await client.getUsage({ groupBy: "user", startDate, endDate });
const summary = summarizeUsageForExternalUser(usage, "naap-user-123");
// summary.requestCount, summary.feeWei

Next.js server-only guard

// lib/pymthouse-server.ts
import "server-only";

export {
  createPmtHouseClientFromEnv,
  getPymthouseBaseUrl,
} from "@pymthouse/builder-sdk/env";

Import createPmtHouseClientFromEnv only from this wrapper in Route Handlers or Server Actions.

Client model — env variable naming and the two-client pattern
API keys — exchanging pmth_* keys for JWTs
Allowances — entitlement balance and manual top-ups
Signer routing — direct DMZ proxy and identity webhook
Token exchange — RFC 8693 and Option A/B flows

Getting started

Core concepts

Authentication

Users

Billing

Infrastructure

Help

Install

Quick start

From environment variables (recommended for server use)

Explicit construction

Environment variables

`PmtHouseClient` method reference

Discovery & OIDC

User management

Token minting & exchange

Device flow

Usage & billing

Signer routing

Subpath exports

Common usage patterns

Construct the client

Mint a user JWT (lazy provisioning)

Mint a signer session for the DMZ

Check usage balance before signing

Usage BFF rollup

Next.js server-only guard

Install

Quick start

From environment variables (recommended for server use)

Explicit construction

Environment variables

PmtHouseClient method reference

Discovery & OIDC

User management

Token minting & exchange

Device flow

Usage & billing

Signer routing

Subpath exports

Common usage patterns

Construct the client

Mint a user JWT (lazy provisioning)

Mint a signer session for the DMZ

Check usage balance before signing

Approve a device login (Option B)

Usage BFF rollup

Next.js server-only guard

Related guides

`PmtHouseClient` method reference