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. Full claim reference: Session tokens.

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

The subject this token acts as. Opaque to Patchwork — compose it server-side from ids that never change.

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 a Patchwork-Signature over your request secret, and — on a minted connection — a short-lived token for the subject. Verifying both is the same work in either integration mode, so it lives on its own page. Signing and verification →

6. Confirm your setup

Press Test on the connection. We post a signed nonce to /patchwork/up and check for a proof only computable with the shared secret. Only verified means the trust is wired correctly — see the health endpoint.

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 @usepatchwork/react for the full surface.

Core objects

Conversations

Delivery

Integrating

Operating

Workbench

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

6. Confirm your setup

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

​6. Confirm your setup

​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

6. Confirm your setup

React