Direct integration

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.

string

required

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

string[]

required

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

string

required

Your user id. Becomes the thread subject.

uuid

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

integer

required

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

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.

Get started

Workbench

Loom

Direct integration

1. Create a signing keypair

2. Publish your public key

3. Mint a session token

4. Call Loom from the browser

5. Verify tool calls you host

React

​1. Create a signing keypair

​2. Publish your public key

​3. Mint a session token

​4. Call Loom from the browser

​5. Verify tool calls you host

​React

1. Create a signing keypair

2. Publish your public key

3. Mint a session token

4. Call Loom from the browser

5. Verify tool calls you host

React