Quickstart

By the end of this guide your backend will be able to:

Authenticate as a machine client (server-to-server)
Provision an end-user in your app’s tenant
Issue a signed, scoped JWT for that user
Gate a request on the user’s entitlement balance
Query usage to confirm metering is working

Time: ~10 minutes
What you need: curl, jq, and credentials from your PymtHouse app registration

Prerequisites

You need three values from your registered developer app. If you don’t have these yet, ask your platform admin or check your app’s settings page.

export BASE_URL="https://your-pymthouse.example"  # or http://localhost:3001 for local dev
export PUBLIC_CLIENT_ID="app_yourClientId"         # public client — appears in JWT claims
export M2M_ID="m2m_yourClientId"                   # M2M client — server-side only
export M2M_SECRET="pmth_cs_yourSecret"             # M2M secret — server-side only

For local development, BASE_URL is http://localhost:3001. Your M2M and public client IDs are created automatically during app setup.

Step 1 — Authenticate your backend

Exchange your M2M credentials for a short-lived machine token. This token authorizes Builder API calls on behalf of your app.

MACHINE_TOKEN=$(curl -sS \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${M2M_ID}" \
  -d "client_secret=${M2M_SECRET}" \
  -d "scope=users:write users:token" \
  "${BASE_URL}/api/v1/oidc/token" | jq -r '.access_token')

echo "Token acquired: ${MACHINE_TOKEN:0:50}..."

You’ll use this token for the next two steps. Machine tokens are short-lived — acquire a fresh one per request batch rather than persisting them.

scope=users:write users:token is the minimum needed for this guide. users:write lets you provision users; users:token lets you mint JWTs for them.

Step 2 — Provision a user

Register a user in your app’s tenant. Use your own identifier — PymtHouse calls this externalUserId. This call is idempotent: running it again updates the existing record instead of creating a duplicate.

curl -sS \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user-123",
    "email": "alice@example.com",
    "status": "active"
  }' \
  "${BASE_URL}/api/v1/apps/${PUBLIC_CLIENT_ID}/users" | jq .

A 200 response confirms the user exists. PymtHouse automatically subscribes new users to the app’s Starter plan — they start with a default $5.00 USD allowance for AI job requests.

Step 3 — Issue a signed user JWT

Mint a short-lived access token scoped to this user. This is what you’ll pass to AI services as proof that this user is authorized to make a request.

USER_JWT=$(curl -sS \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "sign:job" }' \
  "${BASE_URL}/api/v1/apps/${PUBLIC_CLIENT_ID}/users/user-123/token" \
  | jq -r '.access_token')

echo "User JWT: ${USER_JWT:0:60}..."

This JWT has:

sub — the PymtHouse user record id
azp / client_id — your public app_… client id
scope — sign:job (gates this user to AI signing requests)

Pass it as Authorization: Bearer ${USER_JWT} to any PymtHouse-integrated service.

Step 4 — Check the user’s entitlement balance

Before dispatching an AI request, verify the user has remaining balance. This is the access gate.

curl -sS \
  -u "${M2M_ID}:${M2M_SECRET}" \
  "${BASE_URL}/api/v1/apps/${PUBLIC_CLIENT_ID}/usage/balance?externalUserId=user-123" | jq .

Response:

{
  "hasAccess": true,
  "balanceUsdMicros": "5000000",
  "remainingUsdMicros": "5000000",
  "consumedUsdMicros": "0",
  "lifetimeGrantedUsdMicros": "5000000"
}

hasAccess: true means the user can proceed. Gate your request on this field. When the balance is exhausted, hasAccess becomes false and the signer will reject requests with trial_credits_exhausted.

Step 5 — Query usage

After your first AI request goes through, verify it was metered:

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

Usage appears here after the OpenMeter collector ingests the signed-ticket event from the AI backend. There is a short async delay (typically under 30 seconds in production).

What’s next

You have the core flow working. Now wire it into your product:

Integration patterns

Full working examples: SaaS app, CLI device flow, and metered billing. Pick the one that matches your architecture.

Builder SDK

Replace the curl calls with one TypeScript client. mintSignerSessionForExternalUser handles upsert + mint + exchange in one call.

Device flow

Add browser-based login for users authenticating from a CLI or terminal.

Billing setup

Connect Stripe, configure plans, and let users pay for usage beyond the Starter allowance.

SDK equivalent

The entire quickstart in TypeScript using the Builder SDK. See Builder SDK for install instructions and the full method reference.

import { PmtHouseClient, PmtHouseError } 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!,
  // Set to true for local dev when issuer URL is http://
  allowInsecureHttp: process.env.PYMTHOUSE_ALLOW_INSECURE_HTTP === "1",
});

// Steps 2–3: mint user JWT (auto-provisions on first call via 404-retry)
async function mintUserToken(externalUserId: string): Promise<string> {
  try {
    const { access_token } = await client.mintUserAccessToken({ externalUserId });
    return access_token;
  } catch (err) {
    if (err instanceof PmtHouseError && err.status === 404 && err.code === "not_found") {
      await client.upsertAppUser({ externalUserId });
      const { access_token } = await client.mintUserAccessToken({ externalUserId });
      return access_token;
    }
    throw err;
  }
}

// Step 4: check balance before dispatching
const balance = await client.getUsageBalance("user-123");
if (!balance.hasAccess) {
  throw new Error("Insufficient balance — top up or upgrade plan");
}

// Step 3: mint the token
const userJwt = await mintUserToken("user-123");
console.log("User JWT:", userJwt.slice(0, 40) + "...");

Getting started

Core concepts

Authentication

Users

Billing

Infrastructure

Help

Prerequisites

Step 1 — Authenticate your backend

Step 2 — Provision a user

Step 3 — Issue a signed user JWT

Step 4 — Check the user’s entitlement balance

Step 5 — Query usage

What’s next

Integration patterns

Builder SDK

Device flow

Billing setup

SDK equivalent

​Prerequisites

​Step 1 — Authenticate your backend

​Step 2 — Provision a user

​Step 3 — Issue a signed user JWT

​Step 4 — Check the user’s entitlement balance

​Step 5 — Query usage

​What’s next

Integration patterns

Builder SDK

Device flow

Billing setup

​SDK equivalent

Prerequisites

Step 1 — Authenticate your backend

Step 2 — Provision a user

Step 3 — Issue a signed user JWT

Step 4 — Check the user’s entitlement balance

Step 5 — Query usage

What’s next

SDK equivalent