Skip to content

With AgentPod and SuperPipeline

Open as Markdown

In this release, we build a run document from two product views: the run comes from SuperPipeline and its attempts come from the AgentPod hub. SuperWitness reads both over their APIs, as a service principal of the AgentPod hub, and owns none of what it reads. This page follows the credential, the routes and the status mapping so you can see every trust boundary rather than taking “the integration” as a mysterious third product.

Neither product requires SuperWitness. They send plain OTLP to the collector and never wait on SuperWitness, and SuperWitness only ever reads from them.

SuperWitness authenticates to both products with one AgentPod service credential:

Setting Holds
SW_HUB_URL the AgentPod hub, for example https://hub.agentpod.dev
SW_HUB_CLIENT_ID the credential’s id, svc_…
SW_HUB_CLIENT_SECRET_FILE a file holding the credential’s secret alone, readable by its owner only

Create the credential at the hub as a service principal for SuperWitness with the evidence:read and transcripts:read scopes. With evidence:read alone everything works except transcripts, which answer 502 hub_refused. SuperWitness refuses to start if the secret file is empty, or readable by group or others.

Under the organization plane (SW_ORG_PLANE_ISSUER set), SuperWitness signs in with the plane service credential in SW_ORG_PLANE_SERVICE_CREDENTIAL_FILE instead, and SW_HUB_CLIENT_ID and SW_HUB_CLIENT_SECRET_FILE are not used (Configuration).

To read, SuperWitness exchanges the credential for a short-lived token:

POST {SW_HUB_URL}/api/auth/service-token
Authorization: Bearer <SW_HUB_CLIENT_ID>:<secret>

The hub answers {"token": …, "expiresIn": <seconds>}. SuperWitness keeps the token until 30 seconds before it expires, and uses the same token for every request to the hub and to SuperPipeline. If the hub refuses the credential (400, 401 or 403), the sources that need it report unauthorized. If a product answers 401 or 403, SuperWitness drops the token and exchanges again on the next read.

From the hub at SW_HUB_URL, with the service token:

Request For
GET /api/evidence/runs/superpipeline/{run} the run’s ledger: its attempts, each attempt’s fingerprint and agent principal, and the dispatch outcome
GET /api/evidence/attempts/{attempt} which run an attempt belongs to, for GET /v1/runs/by-attempt/{attempt} and attempt verdicts
GET /api/evidence/principals/{id} a principal’s kind, to show a gate’s judge and judge kind; {id} is a prn_… id or a hub user id
GET /health /health’s agentpod status (no token)

And, without a token, the hub’s published keys at GET /api/auth/jwks, to verify the tokens callers present (below).

A run the ledger knows on a different board from the one asked for counts as not found.

What SuperWitness reads from SuperPipeline

Section titled “What SuperWitness reads from SuperPipeline”

From SuperPipeline at SW_SUPERPIPELINE_URL, for example https://app.superpipeline.dev, with the same service token:

Request For
GET {SW_SUPERPIPELINE_URL}/v1/boards/{board}/runs/{run}/evidence the run, its card, stage and state, its agent, its gates, and its usage
GET /health /health’s superpipeline status (no token)

When SuperPipeline cannot answer, the run document falls back to what the AgentPod ledger knows about the run (Concepts).

For both products:

Answer Source status
200 with a body that parses ok
401 or 403 unauthorized
404 with the product’s own not-found error not_found
any other 404, or any other status unavailable
no answer within SW_SOURCE_TIMEOUT timeout
an answer about a different run unavailable

The product’s not-found error is {"error": "not_found"} from the hub, and an error whose code is RUN_NOT_FOUND or BOARD_NOT_FOUND from SuperPipeline. A bare 404, such as a route that is not deployed, is unavailable, so a missing route never reads as a missing run.

Every /v1 route and /mcp take a bearer token from one issuer: the AgentPod hub, or, when SW_ORG_PLANE_ISSUER is set, the organization plane, and then hub tokens are refused. With the hub as issuer, SuperWitness verifies a token offline, against the keys from {SW_HUB_URL}/api/auth/jwks, and accepts it only when:

  • it is an EdDSA (Ed25519) JWT whose key id is among the hub’s published keys;
  • its issuer (iss) is SW_HUB_URL;
  • its audience (aud) includes SW_PUBLIC_URL;
  • it has an expiry (exp) that has not passed and an issued-at time (iat), with 30 seconds of clock leeway;
  • it names a subject (sub) and a tenant, and its principalKind is human, agent or service.

Both URLs are compared as configured, less any trailing /.

If the token has a scope claim, SuperWitness reads it as a space-separated list. Two things need a scope today: POST /v1/runs needs runs:write, from a service principal (Run registry API), and reading transcripts with a token needs transcripts:read (Transcripts). A scope claim that is not a string makes the token invalid.

Under the organization plane (SW_ORG_PLANE_ISSUER set), SuperWitness follows the suite’s access-token rules, the same in every product’s verifier and tested against treaty’s signed token vectors. The issuer is that exact value and the keys come from SW_ORG_PLANE_JWKS_URL; only Ed25519 keys are used, and a token must name one by kid. It accepts a token only when:

  • it is an EdDSA JWT whose audience (aud) is, or includes, SW_PUBLIC_URL;
  • exp and iat are present, exp has not passed, and neither iat nor a nbf is in the future, each with 30 seconds of clock leeway; and it lives at most 300 seconds (exp - iat);
  • it carries jti, principalKind (human, agent or service), org and ent in place of tenant, and the control pair: mayDispatch, a list of prn_ ids (any other value refuses the token), and mayGrantReach, a boolean;
  • sub and org follow the id grammar exactly: prn_ or org_ and 20 lowercase hex characters;
  • every optional claim it carries (act, email, email_verified, scope, amr, orgRole, client_id, azp, sid) has its type.

SuperWitness reads scope only from agent and service tokens. A token whose ent claim lacks superwitness is answered 403 {"error":"product_not_enabled","org":"org_…"}.

Every such principal is admitted; which principals can get a token for SuperWitness’s audience is decided at the hub. The principal kind decides how its verdicts are recorded: their judge_kind, their default kind, and whether it may judge work it executed (Verdicts).

SuperWitness keeps the hub’s keys for 10 minutes. A token with an unknown key id makes it fetch the keys again, at most once every 10 seconds. If the hub cannot be reached, keys it already holds keep working.

A missing or refused token is 401 unauthenticated, with WWW-Authenticate: Bearer realm="superwitness":

{"error":{"code":"unauthenticated","message":"the bearer token is not valid for this service"}}

With no token at all, the message is a bearer token is required.

In fake mode (SW_FAKE_SOURCES=1) none of this applies: SuperWitness reads no product and accepts development tokens of the form dev:<principal>:<human|agent|service> instead (Install). That gives you a clean local path for learning the document; switching to real sources then means replacing the fixtures with the exact reads and token checks above, not changing what a run means.