Skip to main content
A working integration and a production one differ in a handful of places. None are large; all are easier before you have traffic.

​
Credentials

  • Rotate your workspace key out of anywhere it was pasted during development. It can assert any subject in your workspace, so treat it like a database password.
  • Never ship sk_… to a client. If a browser or mobile app needs to talk to us, that is direct, not relay with a shared key.
  • Set allowed origins on the workspace for direct integrations. No wildcards.
  • Plan key rotation before you need it: add the new key to your JWKS alongside the old one, switch kid, then remove the old key once no tokens reference it.

​
Subjects

Get the grain right before you have real partitions to migrate — because you cannot migrate them.
  • Composite subjects for multi-tenant products, derived server-side. See Composite subjects.
  • No PII in the string. It lands in responses, events, and logs.
  • Namespace by source if subjects come from more than one system.
  • Wire account deletion to the memory erasure step.

​
Guardrails

  • Review every wired patch’s permission. Anything that moves money, sends a message, or changes a record should be Always ask — see Confirmations.
  • Declare redaction on patches whose results contain things the model has no business reasoning over.
  • Check risk levels are honest. They drive how prominently your UI asks.

​
Handling failure

  • Handle 429 with Retry-After, and read the RateLimit-* headers to self-pace.
  • Handle 402 — a workspace out of credits is a foreseeable state, not an exception.
  • Branch on error.code, never on error.message. Codes are stable; messages are not.
  • Expect runs to pause. A production client must handle awaiting_input and awaiting_outcome, not just closed.

​
Verification

  • Verify Patchwork-Signature on every tool call, using the raw body and a constant-time compare. See Signing and verification.
  • Press Test on each connection and confirm it reports verified, not merely reachable.
  • Verify webhook deliveries with the endpoint’s own secret, and deduplicate on Patchwork-Delivery.

​
Pinning

Agent ids name one exact version, so nothing changes under you — but that also means improvements do not arrive on their own. Decide who updates the pinned id, and when.

​
Observability

  • Keep the run_id in your own logs. It is the join key to the trace.
  • Sample traces on real traffic early. Most surprises are visible in tool call args long before anyone complains.