Session tokens

In direct integration the browser holds no workspace secret. It holds a token your backend signed for one user, valid for a couple of minutes.

Claims

string

required

Your API key public id (key_…), not the secret. Routes the token to your workspace.

string

required

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

string[]

required

Must include patchwork. Include your own API audience too, so the same token passes your tool middleware.

integer

required

Keep it short — around 120 seconds. The browser remints as needed.

uuid

The connection this token may use. A UUID — not a name. Required when the agent has unpinned customer tools.

string

required

JWT header, not a claim. Names the signing key so we can match it in your JWKS.

Algorithms

RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512. Symmetric algorithms (HS*) are rejected. A shared secret would mean we could mint tokens as you, which is exactly the property the design refuses.

Publishing your key

Serve a JWKS document at a stable URL and set it on the workspace. We fetch and cache it, matching tokens to keys by kid. Rotation is adding a new key alongside the old one and switching kid when you are ready — never removing the old key first. If you cannot host a JWKS URL, paste the public key in the dashboard instead.

Minting

The endpoint that issues these tokens serves two callers — your browser, and the Patchwork runtime minting server-to-server. A connection declares only one mint URL, so both live at one path. The mint endpoint covers the branch, the relay response contract, and why the Playground depends on it. The direct half looks like this:

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

Derive sub from your server session, never from a request parameter. We do not know what your subject string means, so we cannot tell that a user asked for a tenant they do not belong to. See Subjects.

Verification and precedence

A JWT that matches no keyed workspace, or fails signature or claim checks, is rejected — never downgraded to relay. When a session token is present, its sub wins and any subject_ref in the body is ignored.

Core objects

Conversations

Delivery

Integrating

Operating

Workbench

Claims

Algorithms

Publishing your key

Minting

Verification and precedence

​Claims

​Algorithms

​Publishing your key

​Minting

​Verification and precedence

Claims

Algorithms

Publishing your key

Minting

Verification and precedence