Direct integration

The browser talks to Patchwork. Your backend mints a short-lived session token.

Direct is the default for a product UI. The browser never sees a workspace API key.

browser  ── mint (your user session) ──▶  your backend     signs with your private key
browser  ── Bearer <token> ────────────▶  Patchwork        verifies with your public key
Patchwork ── token + signature ────────▶  your tool        runs as the user

1. Create a signing keypair

Generate an RSA (or EC) keypair. The private key signs tokens and never leaves your servers. The public key is what Patchwork uses to verify — it is not a secret.

openssl genrsa -out patchwork-private.pem 2048
openssl rsa -in patchwork-private.pem -pubout -out patchwork-public.pem

Allowed algorithms: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512. Symmetric (HS*) is rejected.

2. Publish your public key

Serve the public key as a JWKS document at a stable URL. Patchwork fetches and caches it, matching each token to a key by kid. Rotation is adding a new key alongside the old one.

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "your-app-2026-01",
      "n": "0vx7ag…",
      "e": "AQAB"
    }
  ]
}

If you cannot host a JWKS URL, paste the public key in the dashboard instead.

In Connections, create a host (name + base_url) and set workspace ingress: JWKS URI, allowed origins, request secret, mint URL. Allowed origins are required so the browser can call Patchwork — no wildcards.

3. Mint a session token

Add one endpoint to your backend, authenticated by your existing user session. It returns a short-lived JWT signed with your private key.

iss · string · required

Your API key public id (key_…), not the secret.

aud · string[] · required

Must include patchwork. Include your own API audience as well so the same token can pass your tool middleware.

sub · string · required

Your user id. Becomes the thread subject.

conn · uuid

Connection id this token may call. A UUID — not a name, not a URL. Required when the agent has unpinned customer tools.

exp · integer · required

Unix timestamp. Keep it short — about 120 seconds. The browser remints as needed.

kid · string · required

JWT header. Names the signing key so we match it in your JWKS.

import jwt from "jsonwebtoken";

app.post("/patchwork/mint", requireUser, (req, res) => {
  const token = jwt.sign(
    {
      iss: PATCHWORK_API_KEY_ID,
      aud: ["patchwork", "your-api"],
      sub: req.user.id,
      conn: CONNECTION_ID,
    },
    PRIVATE_KEY,
    { algorithm: "RS256", expiresIn: 120, keyid: "your-app-2026-01" },
  );

  res.json({ token, expires_in: 120, subject_ref: req.user.id });
});

Do not put a workspace secret (sk_…) in the browser. The session token is the only credential the client holds, and it expires in minutes. A token must authorize no more than the user could do themselves.

4. Call Loom from the browser

async function mint() {
  const res = await fetch("/patchwork/mint", { method: "POST" });
  const { data } = await res.json();
  return data.token;
}

const thread = await fetch("https://api.usepatchwork.co/v1/loom/threads", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${await mint()}`,
  },
  body: JSON.stringify({ agent: "agent_…" }),
}).then((r) => r.json());

const accepted = await fetch(
  `https://api.usepatchwork.co/v1/loom/threads/${thread.data.id}/messages`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${await mint()}`,
    },
    body: JSON.stringify({ content: "Send 50 USDC to Jane" }),
  },
).then((r) => r.json());

The message response is 202 with a run_id. Poll GET /v1/loom/runs/:id or subscribe to the thread channel — see Realtime.

5. Verify tool calls you host

Every call we make to your backend carries the session token and a Patchwork-Signature over your request secret. A stolen token is useless without the secret.

import crypto from "crypto";
import jwt from "jsonwebtoken";

function verifyPatchwork(req, res, next) {
  const header = req.get("Patchwork-Signature");
  if (!header) return res.status(401).end();

  const { t, v1 } = Object.fromEntries(
    header.split(",").map((pair) => pair.split("=")),
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.status(401).end();

  const digest = crypto.createHash("sha256").update(req.rawBody ?? "").digest("base64");
  const payload = `${t}.${req.method}.${req.path}.${digest}`;
  const expected = crypto
    .createHmac("sha256", REQUEST_SECRET)
    .update(payload)
    .digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
    return res.status(401).end();
  }

  const claims = jwt.verify(bearer(req), PUBLIC_KEY, {
    algorithms: ["RS256"],
    audience: "your-api",
  });

  req.user = { id: claims.sub };
  next();
}

Verify the signature, verify the token, then hydrate your normal request context. Your existing authorization runs unchanged.

React

@usepatchwork/react wraps the browser side. You provide url and a mint function that returns the session token. Optional connection pins the host.

<PatchworkProvider
  url="https://api.usepatchwork.co"
  connection={CONNECTION_ID}
  mint={async () => {
    const res = await fetch("/patchwork/mint", { method: "POST" });
    const { data } = await res.json();
    return data.token;
  }}
>
  <Chat />
</PatchworkProvider>

useAgent gives you messages, threads, send, openThread, and newChat. See the package readme.