Deprecated routes and migrations

This page documents endpoints that have been removed (returning 410 Gone) or deprecated across PymtHouse versions. Follow the migration steps for your version to update your integration.

v0.3.5 – v0.3.7 breaking changes

Auth validate endpoint changed

- GET /api/v1/auth/validate
+ POST /api/v1/auth/validate
  Content-Type: application/json
  { "key": "pmth_…" }

Set BPP_VALIDATE_V2=1 in your environment to opt into the new POST form. The GET form is removed.

Builder API surface split

Routes are now grouped by audience. Usage API paths moved to the canonical builder prefix:

- GET /api/v1/apps/{clientId}/usage
+ GET /api/v1/builder/apps/{clientId}/usage

The legacy /api/v1/apps/{clientId}/usage* paths remain as deprecated M2M-only aliases. Migrate to /api/v1/builder/apps/{clientId}/usage*.

Bearer tokens are rejected on all usage paths. Use HTTP Basic auth (-u m2m_id:pmth_cs_secret) for all usage queries, including the legacy aliases.

Signer session exchange endpoint replaced

- POST /api/v1/apps/{clientId}/auth/api-key/signer-session
+ POST /api/v1/apps/{clientId}/oidc/token
  grant_type=urn:ietf:params:oauth:grant-type:token-exchange
  subject_token=pmth_...
  subject_token_type=urn:ietf:params:oauth:token-type:access_token

- POST /api/v1/apps/{clientId}/auth/api-key/token
+ POST /api/v1/apps/{clientId}/oidc/token
  (same RFC 8693 form)

The issuer-level endpoint POST /api/v1/oidc/token is also accepted and resolves the app from the credential.

App-level keys replaced by per-user keys

- GET    /api/v1/apps/{clientId}/keys
- POST   /api/v1/apps/{clientId}/keys
- DELETE /api/v1/apps/{clientId}/keys
+ GET    /api/v1/apps/{clientId}/users/{externalUserId}/keys
+ POST   /api/v1/apps/{clientId}/users/{externalUserId}/keys
+ DELETE /api/v1/apps/{clientId}/users/{externalUserId}/keys

Builder-minted per-user keys now use the composite format app_<24hex>_<secret> so the remote-signer identity webhook can recover client_id from the credential. Personal keys remain bare pmth_<hex>.

Discovery pricing endpoint removed

- GET /api/v1/apps/{clientId}/discovery/pricing

Removed in v0.3.7. Read routing information from the signer routing endpoint instead:

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

Auto top-up removed

The per-user off-session-charge (auto top-up) design was built and retired mid-v0.3.7 development in favor of invoice-based collection. Do not build against any pymthouse_auto_topup metadata. Use Builder M2M Payments API → Overage gate for ongoing spend collection.

Subscription CRUD (v0.3.7)

- GET/POST/DELETE /api/v1/subscriptions

Replaced by:

Old	New
`POST /api/v1/subscriptions`	`POST .../users` + OpenMeter checkout
`DELETE /api/v1/subscriptions`	`DELETE .../plans?planId=`
`GET /api/v1/subscriptions`	`GET .../plans` or `GET .../users/{id}/subscription`

Balance gate `expiryTtl`

The signer now receives expiryTtl explicitly. If you cached gate decisions, verify your cache TTL assumptions match the new value.

v0.2.x breaking changes

Hosted signer proxy removed (`/api/signer/*`)

Affected routes (all return 410 Gone):

Route	Removed
`POST /api/signer/generate-live-payment`	v0.2.x
`POST /api/signer/sign-orchestrator-info`	v0.2.x
`POST /api/signer/sign-byoc-job`	v0.2.x
`GET /api/signer/discover-orchestrators`	v0.2.x

Why it was removed

The hosted /api/signer/* HTTP proxy was a synchronous pass-through between your backend and the go-livepeer DMZ. It created a PymtHouse-hosted bottleneck on the signing hot path and was incompatible with direct DMZ deployments.

Migration

Step 1: Fetch the remote DMZ URL and webhook URL for your app:

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

Response includes dmzUrl and webhookUrl. Step 2: Use @pymthouse/builder-sdk/signer/server to proxy requests directly to the DMZ:

import { createDirectSignerProxyHandler } 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,
});

Step 3: Set up the go-livepeer identity webhook using @livepeer/clearinghouse-identity-webhook:

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));
}

See Signer routing for the full setup guide.

POST /api/signer/device/exchange is not removed — it is an active SDK helper for device token → signer JWT exchange. Only the generate-live-payment, sign-orchestrator-info, sign-byoc-job, and discover-orchestrators proxy routes are gone.

Synchronous signed-ticket ingest removed

Affected route:

Route	Status
`POST /api/v1/apps/{clientId}/usage/signed-tickets`	`410 Gone`

Why it was removed

Synchronous HTTP ingest on the signing hot path added latency and created a PymtHouse-side bottleneck. Production metering is now asynchronous: go-livepeer emits create_signed_ticket events to Kafka (livepeer-gateway-events); the OpenMeter collector consumes Kafka and writes CloudEvents to OpenMeter/Konnect.

Migration

No direct replacement for synchronous ingest from your backend. Metering is handled by the go-livepeer DMZ and Kafka collector automatically when signing requests are processed through the DMZ. Diagnostic-only ingest remains available at:

POST /api/v1/ingest/events
Authorization: Bearer INGEST_SHARED_SECRET

This endpoint is for monitoring and diagnostics only — it does not write authoritative billing usage to OpenMeter. To verify usage is flowing, query the Usage API after signing requests:

curl -sS \
  -u "${M2M_ID}:${M2M_SECRET}" \
  "${BASE_URL}/api/v1/apps/${CLIENT_ID}/usage?groupBy=pipeline_model" | jq .

Subscription CRUD removed (v0.2.x)

Affected routes:

Route	Status	Replacement
`POST /api/v1/subscriptions`	`410 Gone`	Use `POST .../plans` + OpenMeter checkout
`DELETE /api/v1/subscriptions`	`410 Gone`	Use `DELETE .../plans?planId=`
`GET /api/v1/subscriptions`	Deprecated (returns legacy cache rows)	Use `GET .../plans` or `GET .../users/{id}/subscription`

Manage subscriptions through the plans CRUD API (dashboard session) or the OpenMeter billing checkout flow. See Plans and Allowances.

Deprecated `credits` alias

Affected routes:

Route	Status	Replacement
`GET .../users/{id}/credits`	Deprecated alias	`GET .../users/{id}/allowances`
`POST .../users/{id}/credits`	Removed / redirects	`POST .../users/{id}/allowances`

The credits endpoints re-export the allowances endpoints. The POST route has been removed from PymtHouse. Update all references:

- GET /api/v1/apps/{clientId}/users/{externalUserId}/credits
+ GET /api/v1/apps/{clientId}/users/{externalUserId}/allowances

- POST /api/v1/apps/{clientId}/users/{externalUserId}/credits
+ POST /api/v1/apps/{clientId}/users/{externalUserId}/allowances

SDK:

- await client.getUserCredits(externalUserId)
+ await client.getUserAllowances(externalUserId)

- await client.grantUserCredits(externalUserId, input)
+ await client.grantUserAllowance(externalUserId, input)

App manifest routes deprecated

Affected routes:

Route	Status
`GET /api/v1/apps/{clientId}/manifest`	Deprecated — returns fail-open stub only
`PUT /api/v1/apps/{clientId}/manifest`	Deprecated

The manifest API was used to configure discoverable pipeline/model combinations (subtractive exclusions). The signing hot path no longer enforces capability restrictions; GET .../manifest returns a fail-open stub (capabilities: []) rather than a resolved list. Manage capability exclusions through the Plans UI instead. SDK methods deprecated:

Method	Replacement
`getAppManifest({ ifNoneMatch? })`	Plans UI
`parseAppManifestResponse(raw)`	N/A
`computeManifestRevision(parsed)`	N/A

Deprecated discovery profiles

Affected routes:

Route	Status
`GET/POST .../discovery-profiles`	Legacy — still functional, not removed
`GET/PUT/DELETE .../discovery-profiles/{id}`	Legacy — still functional, not removed

Discovery profiles are a legacy mechanism for expressing pipeline/model capability sets on plans. They remain functional for backward compatibility but new integrations should use the Plans UI for network capability management.

Summary table

Route	Status	Replacement
`GET /api/v1/auth/validate`	Removed	`POST /api/v1/auth/validate` with `{ key }`
`GET/POST/DELETE /api/v1/apps/{clientId}/keys`	Replaced	`…/users/{externalUserId}/keys`
`POST .../auth/api-key/signer-session`	Replaced	`POST .../oidc/token` (RFC 8693)
`POST .../auth/api-key/token`	Replaced	`POST .../oidc/token` (RFC 8693)
`GET /api/v1/apps/{clientId}/usage*`	Deprecated alias	`GET /api/v1/builder/apps/{clientId}/usage*`
`GET /api/v1/apps/{clientId}/discovery/pricing`	Removed	`GET .../signer/routing`
`POST /api/signer/generate-live-payment`	`410 Gone`	`createDirectSignerProxyHandler` + DMZ
`POST /api/signer/sign-orchestrator-info`	`410 Gone`	Direct DMZ
`POST /api/signer/sign-byoc-job`	`410 Gone`	Direct DMZ
`GET /api/signer/discover-orchestrators`	`410 Gone`	Plans UI
`POST .../usage/signed-tickets`	`410 Gone`	Kafka async metering (no replacement)
`POST /api/v1/subscriptions`	`410 Gone`	Plans CRUD + checkout
`DELETE /api/v1/subscriptions`	`410 Gone`	Plans CRUD
`POST .../users/{id}/credits`	Removed	`POST .../users/{id}/allowances`
`GET .../users/{id}/credits`	Deprecated alias	`GET .../users/{id}/allowances`
`getUserCredits()` SDK method	Deprecated	`getUserAllowances()`
`grantUserCredits()` SDK method	Deprecated	`grantUserAllowance()`
`ingestSignedTicket()` SDK method	Legacy	No direct replacement (Kafka handles metering)
`GET .../manifest`	Deprecated	Plans UI
`PUT .../manifest`	Deprecated	Plans UI
`getAppManifest()` SDK method	Deprecated	Plans UI

Getting started

Core concepts

Authentication

Users

Billing

Infrastructure

Help

Deprecated routes and migrations

v0.3.5 – v0.3.7 breaking changes

Auth validate endpoint changed

Builder API surface split

Signer session exchange endpoint replaced

App-level keys replaced by per-user keys

Discovery pricing endpoint removed

Auto top-up removed

Subscription CRUD (v0.3.7)

Balance gate `expiryTtl`

v0.2.x breaking changes

Hosted signer proxy removed (`/api/signer/*`)

Why it was removed

Migration

Synchronous signed-ticket ingest removed

Why it was removed

Migration

Subscription CRUD removed (v0.2.x)

Deprecated `credits` alias

App manifest routes deprecated

Deprecated discovery profiles

Summary table

​v0.3.5 – v0.3.7 breaking changes

​Auth validate endpoint changed

​Builder API surface split

​Signer session exchange endpoint replaced

​App-level keys replaced by per-user keys

​Discovery pricing endpoint removed

​Auto top-up removed

​Subscription CRUD (v0.3.7)

​Balance gate expiryTtl

​v0.2.x breaking changes

​Hosted signer proxy removed (/api/signer/*)

​Why it was removed

​Migration

​Synchronous signed-ticket ingest removed

​Why it was removed

​Migration

​Subscription CRUD removed (v0.2.x)

​Deprecated credits alias

​App manifest routes deprecated

​Deprecated discovery profiles

​Summary table

v0.3.5 – v0.3.7 breaking changes

Auth validate endpoint changed

Builder API surface split

Signer session exchange endpoint replaced

App-level keys replaced by per-user keys

Discovery pricing endpoint removed

Auto top-up removed

Subscription CRUD (v0.3.7)

Balance gate `expiryTtl`

v0.2.x breaking changes

Hosted signer proxy removed (`/api/signer/*`)

Why it was removed

Migration

Synchronous signed-ticket ingest removed

Why it was removed

Migration

Subscription CRUD removed (v0.2.x)

Deprecated `credits` alias

App manifest routes deprecated

Deprecated discovery profiles

Summary table