Signer routing

Direct signer integration uses:

GET .../signer/routing — fetch the DMZ URL and webhook URL for your app.
@pymthouse/builder-sdk/signer/server — proxy signing requests directly to the remote signer DMZ with JWT minting.
@livepeer/clearinghouse-identity-webhook — handle go-livepeer identity webhook calls (POST /authorize) to authenticate end-users.

Token lifecycle

The following diagram shows how a signing request flows from the app backend through PymtHouse to the remote signer DMZ:

Fetch signer routing config

GET /api/v1/apps/{clientId}/signer/routing
Authorization: Basic base64(m2m_id:m2m_secret)

Returns the remote DMZ URL, JWKS URL, webhook URL, and metering mode for the app. Response:

{
  "dmzUrl": "https://dmz.example.com",
  "jwksUrl": "https://your-pymthouse.example/api/v1/oidc/jwks",
  "webhookUrl": "https://your-app.example/authorize",
  "meteringMode": "kafka"
}

Field	Description
`dmzUrl`	The remote signer DMZ base URL. Forward signing requests here.
`jwksUrl`	PymtHouse JWKS endpoint for the DMZ to validate JWTs.
`webhookUrl`	The identity webhook URL configured on the go-livepeer DMZ (`-remoteSignerWebhookUrl`).
`meteringMode`	`"kafka"` (async Kafka collector) or `"direct"`.

SDK:

const routing = await client.getSignerRouting();
// routing.dmzUrl, routing.webhookUrl

Direct DMZ proxy (`@pymthouse/builder-sdk/signer/server`)

Use createDirectSignerProxyHandler to build an HTTP handler in your backend that:

Mints a user JWT (or signer session) via the Builder API or OIDC.
Forwards the original signing request to the remote DMZ with the JWT as the Bearer token.
Streams the response back to the caller.

import { createDirectSignerProxyHandler, createSignerTokenManager } from "@pymthouse/builder-sdk/signer/server";
import { createPmtHouseClientFromEnv } from "@pymthouse/builder-sdk/env";

const client = createPmtHouseClientFromEnv();
const routing = await client.getSignerRouting();

const handler = createDirectSignerProxyHandler({
  client,
  dmzUrl: routing.dmzUrl,
  // Optional: cache signer tokens to reduce round-trips
  tokenManager: createSignerTokenManager({ client }),
});

// In your HTTP framework:
export async function POST(request: Request) {
  return handler(request);
}

Low-level helpers

For custom forwarding logic:

import {
  forwardDirectSignerRequest,
  mintUserSignerToken,
} from "@pymthouse/builder-sdk/signer/server";

// Mint a signer JWT for a specific user
const token = await mintUserSignerToken(client, {
  externalUserId: "user-123",
  scope: "sign:job",
});

// Forward to DMZ with the token
const response = await forwardDirectSignerRequest({
  dmzUrl: routing.dmzUrl,
  signerToken: token.access_token,
  request: incomingRequest,
});

Device and API key exchange handlers

For CLI device flows and API key integrations, builder-sdk provides purpose-built handlers:

import {
  createDeviceExchangeHandler,
  createApiKeyExchangeHandler,
} from "@pymthouse/builder-sdk/signer/server";

// POST /api/signer/device/exchange — device token → signer JWT
const deviceExchange = createDeviceExchangeHandler({ client });

// POST /api/signer/api-key/exchange — API key → signer session via facade
const apiKeyExchange = createApiKeyExchangeHandler({
  client,
  facadeUrl: process.env.DASHBOARD_ORIGIN!,
});

Identity webhook (`@livepeer/clearinghouse-identity-webhook`)

go-livepeer calls your identity webhook (configured via -remoteSignerWebhookUrl) for every signing request to verify the end-user’s credentials and receive an auth_id for usage attribution. Set the flag to the exact path for your deployment:

Deployment	`-remoteSignerWebhookUrl`
Embedded in PymtHouse	`https://<your-pymthouse-host>/webhooks/remote-signer`
Standalone clearinghouse sidecar	`https://<webhook-host>/authorize`

PymtHouse embeds the clearinghouse package at POST /webhooks/remote-signer. The same package runs as a standalone sidecar (listening at POST /authorize) in the clearinghouse compose stack.

Setup (embedded in your app)

import { handleAuthorize } from "@livepeer/clearinghouse-identity-webhook/protocol";
import { createLegacyWebhookConfigFromEnv } from "@livepeer/clearinghouse-identity-webhook/legacy-env";

export async function POST(request: Request) {
  return handleAuthorize(request, createLegacyWebhookConfigFromEnv(process.env));
}

End-user auth modes

Set IDENTITY_AUTH_MODE when running the standalone sidecar (api_key or oidc). For embedded Pymthouse routes, createLegacyWebhookConfigFromEnv maps legacy JWT_* / CLAIM_* env vars to OIDC verification.

Mode	Package import	Use case
OIDC (Pymthouse default)	`legacy-env` + `JWT_ISSUER`	PymtHouse-issued JWTs or Auth0/OIDC tokens
API key (sidecar)	`verifiers` + `createApiKeyVerifier`	Demo `sk_…` keys or custom key store
OIDC (sidecar)	`verifiers` + `createEndUserVerifierFromEnv`	Auth0 / generic OIDC with `OIDC_*` env vars

API key mode (sidecar)

import { handleAuthorize } from "@livepeer/clearinghouse-identity-webhook/protocol";
import { createApiKeyVerifier } from "@livepeer/clearinghouse-identity-webhook/verifiers";

const config = {
  webhookSecret: process.env.WEBHOOK_SECRET!,
  endUserAuth: createApiKeyVerifier({
    issuer: process.env.IDENTITY_ISSUER!,
    resolveApiKey: async (key) => (await lookup(key)) ?? null,
  }),
};

export async function POST(request: Request) {
  return handleAuthorize(request, config);
}

Webhook environment variables

Variable	Description
`WEBHOOK_SECRET`	Shared secret between go-livepeer DMZ and your webhook handler. Set on the DMZ via `-remoteSignerWebhookSecret`.
`JWT_ISSUER`	OIDC issuer URL for JWT validation (e.g. `https://your-pymthouse.example/api/v1/oidc`).
`JWT_AUDIENCE`	Expected `aud` claim in end-user JWTs.
`CLAIM_CLIENT_ID`	JWT claim to use as the client id (default `azp`; for Auth0 set to `azp`).

Security guidance

WEBHOOK_SECRET authenticates that the signing request came from your go-livepeer DMZ instance. Rotate it if the DMZ is compromised.
The end-user EndUserAuthVerifier authenticates the user making the signing request. Keep the two auth layers separate — webhook secret is transport; end-user auth is identity.
Configure the go-livepeer DMZ with -remoteSignerWebhookUrl pointing to your webhook path (/webhooks/remote-signer when embedded in PymtHouse, /authorize for the standalone sidecar) and -remoteSignerWebhookSecret matching WEBHOOK_SECRET.
The DMZ validates JWTs against the JWKS URL from getSignerRouting() — ensure jwksUrl is reachable from the DMZ host.

Token exchange — minting JWTs and signer sessions
API keys — exchanging pmth_* keys for signer sessions
Builder SDK — createDirectSignerProxyHandler, getSignerRouting
Deprecated routes — migration from the removed /api/signer/* proxy

Getting started

Core concepts

Authentication

Users

Billing

Infrastructure

Help

Token lifecycle

Fetch signer routing config

Direct DMZ proxy (`@pymthouse/builder-sdk/signer/server`)

Low-level helpers

Device and API key exchange handlers

Identity webhook (`@livepeer/clearinghouse-identity-webhook`)

Setup (embedded in your app)

End-user auth modes

API key mode (sidecar)

Webhook environment variables

Security guidance

​Token lifecycle

​Fetch signer routing config

​Direct DMZ proxy (@pymthouse/builder-sdk/signer/server)

​Low-level helpers

​Device and API key exchange handlers

​Identity webhook (@livepeer/clearinghouse-identity-webhook)

​Setup (embedded in your app)

​End-user auth modes

​API key mode (sidecar)

​Webhook environment variables

​Security guidance

​Related guides

Token lifecycle

Fetch signer routing config

Direct DMZ proxy (`@pymthouse/builder-sdk/signer/server`)

Low-level helpers

Device and API key exchange handlers

Identity webhook (`@livepeer/clearinghouse-identity-webhook`)

Setup (embedded in your app)

End-user auth modes

API key mode (sidecar)

Webhook environment variables

Security guidance

Related guides