GRRC Certification — Verification API Reference (v1)

Status: Implementer reference — Phase 34 / Slice 222 (VERIFY-API-COMPLETE). Authored FROM the built endpoints. Pairs with the Independent Verification Specification (the algorithm + formats) and the Bounded-Claim Statement (what verification asserts and does not).

Base path: /api/v1/grrc/verify. All routes key off the abstract role grrc + the robot UUID + a crypto-agile key-id — no operator/company name appears in any route, payload, or identifier (CD #864).

Hosting note. The endpoint is convenience over the offline floor (trust-model (iv-2)): it only restates what an independent offline verifier confirms from the published signed artifacts and anchor. It is never the only path and never a gate. The mirrorable resource endpoints (/bundle, /anchors, /revocation) let a relying party fetch the inputs and verify them themselves, on infrastructure they control. (The production prod-deploy of this surface at the GRRC verification domain is a gated follow-on; the floor is domain-independent.)

Auth tiers

When no verification bundle is provisioned for the robot, every route fails safe with 404 application/problem+json (never 500; the public routes are anonymous, so the 404 — not a 401 — proves the tier is genuinely open).

Public endpoints

GET /api/v1/grrc/verify/{robotUuid}

Confirms the robot's public GRRC certification claim. (iv-3): carries no sequence horizon (a boolean ChainIntegrityConfirmed only — no enumerable timeline; honors S219-CARRY-CHECKPOINT-SEQUENCE-EXPOSURE).

200 body:

{
  "robotUuid": "<guid>",
  "certStatus": "valid | expired | revoked | self-de-certified | superseded | genuineness-failed | integrity-broken | indeterminate",
  "genuinenessConfirmed": <bool>,
  "genuinenessKeyId": "<certifier key-id | null>",
  "chainIntegrityConfirmed": <bool>,
  "overallVerified": <bool>,
  "asOfUtc": "<ISO-8601>",
  "doesNotAssert": "<owner-authored (iv-1) explicit negative, verbatim>"
}

GET /api/v1/grrc/verify/{robotUuid}/bundle

The mirrorable verification bundle — the offline-verifiable artifact JSON (the certifier-signed grant + cert-status checkpoint + signed anchor/revocation statement). Public tier: no chain segment. Content-Type: application/vnd.grrc.verification-bundle.v1+json. Fetch it, re-host it on any mirror, and verify it offline against the published anchor.

GET /api/v1/grrc/verify/{robotUuid}/anchors

The published trusted-anchor set backing this robot's certification ({ FormatVersion, Anchors: [{ KeyId, Algorithm, PublicKeySpkiBase64 }] }). Content-Type: application/vnd.grrc.trust-anchor-set.v1+json. The public key bytes a relying party verifies the bundle against.

GET /api/v1/grrc/verify/{robotUuid}/revocation

The signed, mirrorable revocation / anchor-currency statement ({ FormatVersion, AnchorStatementPayloadBase64 }). Content-Type: application/vnd.grrc.revocation-statement.v1+json. A clearance is current iff its key-id appears in the statement's signed trustedKeyIds; the statement timestamp makes staleness visible. Fetch the freshest copy from any mirror.

Authorized full-record endpoints (developer_mode)

GET /api/v1/grrc/verify/{robotUuid}/full

The authorized verification result: the public bounded result plus the sequence horizon and head hash the (iv-3) boundary keeps off the public tier. When a full-record artifact is provisioned, chainWalkPerformed is true and the result reflects the full independent chain-integrity walk (not the certifier checkpoint alone) — closing the offline-floor's thin-walk residual.

200 body:

{
  "robotUuid": "<guid>", "certStatus": "<token>",
  "genuinenessConfirmed": <bool>, "genuinenessKeyId": "<key-id|null>",
  "chainIntegrityConfirmed": <bool>,
  "intactThroughSequence": <int64|null>, "headChainHashBase64": "<base64|null>",
  "revocationCurrent": <bool>, "overallVerified": <bool>,
  "asOfUtc": "<ISO-8601>", "doesNotAssert": "<(iv-1) verbatim>",
  "chainWalkPerformed": <bool>,
  "diagnostics": [ "<string>", ... ]
}

GET /api/v1/grrc/verify/{robotUuid}/full/record

The authorized full-record artifact — the offline-verifiable artifact carrying the robot's chain segment + the published robot audit public key, so the auditor runs the full independent two-leg verification offline. Content-Type: application/vnd.grrc.full-record.v1+json.

verify ≠ decrypt: the chain segment carries the encrypted envelope (ciphertext) only — never plaintext. It is erasure-compatible by construction. (iv-3): the segment (the event sequence) is served only on this authenticated tier.

Verifying offline (the floor, the architecturally honest path)

The endpoint is a courier; the durable guarantee is offline verification. Reference flow:

1. Fetch /bundle (+ /anchors, /revocation) — or, for the full walk, the authorized /full/record.
2. Cut the network. From here, only the saved files + a verifier are used.
3. Run the offline verifier (the shipped Res.Tools.GrrcVerify, or your own per the Independent Verification Specification):

   Res.Tools.GrrcVerify --artifact <bundle-or-full-record>.json --anchor-pem <anchor>.pem --anchor-key-id <key-id> [--as-of <iso-8601>]
   

   Exit codes: 0 valid · 3 a bounded non-valid status (expired / revoked / superseded / self-de-certified / genuineness-failed / integrity-broken) · 1 indeterminate / usage error.

The offline result is byte-identical to the public endpoint on the bounded fields. That equivalence — endpoint and offline floor agreeing, with the endpoint switched off — is the proof that the hosted path is convenience, never a gate.

Stable, versioned formats

Each resource carries a FormatVersion (or schemaVersion); a consumer must reject a version it does not understand rather than best-effort parse it. Versions bump only on a breaking wire change; additive optional fields keep the version. A GRRC clearance lives ~1 year — verify against this contract for that lifetime.

End of the GRRC Verification API Reference (v1) — Phase 34 / Slice 222. The implementer doc tier (this reference + the spec + the bounded-claim statement) is authored FROM the built resources so it cannot drift from what shipped. The end-user / demo-application packaging of these is a separate follow-on slice.