# 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

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](/use/transcripts/#who-may-read-content), 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](/use/configuration/#settings)).

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.

## 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

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](/concepts/#run)).

## 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

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](/build/run-registry/#who-may-report)), and reading transcripts with a token
needs `transcripts:read` ([Transcripts](/use/transcripts/#who-may-read-content)). 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](/use/verdicts/#subjects-and-who-may-judge-them)).

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"`:

```json
{"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](/install/#try-it-without-the-other-products)). 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.
