Registry Evidence API

View as Markdown

Registry Evidence (Evidence) answers a relying party’s fixed question with a signed assertion. The caller sends a Requirement URI, a purpose, and selector values for the subject, authenticated with an access token, and chooses a response encoding with Accept. Every route, request body, response schema, and problem is in the generated Registry Evidence API operations, rendered from the OpenAPI document the runtime serves.

What the API is

You send POST /v1/evidence with the requirement’s Requirement URI, a purpose, and the selector values that identify the subject. Evidence returns the smallest assertion that answers the requirement, signed, and never the source records behind it. POST /v1/evidence/batch asks the same requirement and purpose for one to sixteen ordered subject sets in one request. GET /v1/evidence-definitions describes the complete request shapes your token may send today, and no others; it is not a public catalog. Each definition carries its handle, Requirement URI, configuration revision, evidence type and kind, purpose, response formats, reference frameworks, subject roles with their selector profiles, and the output concepts and forms it may return. The document also names the deployment’s assurance profile, the audience your token was accepted for, the issuer and provider identities, and the largest holder-bound batch it accepts. Listing reads no source and writes no evidence audit entry. How Evidence works explains the model.

The Version 1 contract is frozen: those three versioned operations and their envelopes are the complete Evidence request surface. The experimental public check route is outside that contract.

Authentication

The three versioned operations require exactly one Authorization header with one Bearer token. The token is an OIDC access token from the one issuer the deployment trusts, for Evidence’s audience, with an accepted token type and signing algorithm, and it carries the principal claim the deployment names. Evidence reads no client_id, azp, header, or request field in its place. GET /.well-known/oauth-protected-resource names the issuer to ask. Request an access token from your own code shows the exchange. The other routes take no credential and reveal no definition or entitlement.

One experimental route is also unauthenticated and reads registry data: POST /v1/public-check, which exists only when the operator activates a public check. It takes a certificate number and its check code, reads no Authorization header or any other request header except Content-Type, and answers one configured requirement. Evidence does not enforce a path restriction: the operator exposes the route only through a path-restricted proxy. See the public certificate check example.

Response encodings

POST /v1/evidence negotiates its encoding from the Accept header:

application/jose+json, the default when Accept is missing or */*: the assertion as a signed flattened JWS that you can verify later against the published keys.
application/dc+sd-jwt: the same assertion as an SD-JWT VC response under the frozen profile in sd-jwt-vc-profile.yaml. It is a second encoding of one response, never a credential lifecycle (Request evidence as an SD-JWT VC).

A grant may also permit the visibly unsigned envelope application/vnd.registrystack.evidence-unsigned+json, which is not later-verifiable evidence, and a holder-bound requirement offers one more encoding, listed with the operations. POST /v1/evidence/batch accepts only application/vnd.registrystack.evidence.request-batch+json and returns one signed flattened JWS per available item. Either route refuses an Accept value it does not offer with format.unsupported (Registry Evidence errors and problems reference).

Registry Evidence API operations