With AgentPod and SuperPipeline
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.
The service credential
Section titled “The service credential”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-tokenAuthorization: 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.
What SuperWitness reads from AgentPod
Section titled “What SuperWitness reads from AgentPod”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).
How answers become statuses
Section titled “How answers become statuses”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.
Tokens callers present
Section titled “Tokens callers present”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) isSW_HUB_URL; - its audience (
aud) includesSW_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 atenant, and itsprincipalKindishuman,agentorservice.
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; expandiatare present,exphas not passed, and neitheriatnor anbfis in the future, each with 30 seconds of clock leeway; and it lives at most 300 seconds (exp - iat);- it carries
jti,principalKind(human,agentorservice),organdentin place oftenant, and the control pair:mayDispatch, a list ofprn_ids (any other value refuses the token), andmayGrantReach, a boolean; subandorgfollow the id grammar exactly:prn_ororg_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.