Registry Notary API

The generated API reference linked above is the authoritative route reference. It is built from Registry Notary’s generated OpenAPI document, synced from the registry-notary repository at the commit pinned in src/data/repo-docs.yaml. This page carries the context the specification does not: how authentication works, how disclosure is controlled, what credentials look like, and what is out of scope.

For exact routes and schemas, read the generated API reference. For setup and operations, see the Registry Notary product documentation.

What the API is

Registry Notary implements the claim-evaluation and credential-issuance parts of the Evidence Gateway pattern. It is a standalone service for claim evaluation, disclosure policy, credential issuance, and audit. A Notary-only deployment supports source-free and self-attested claims. Those claims are evaluation-only. Registry-backed claims use a combined deployment in which Notary calls Registry Relay, and only those claims can enter credential issuance. Callers discover its capabilities and claim catalog at GET /.well-known/evidence-service. This route requires authentication (the same x-api-key or Authorization: Bearer token as other evaluation routes); it is not a public discovery endpoint. The issuer JWKS at GET /.well-known/evidence/jwks.json is public and requires no credentials. The evaluation, rendering, credential, and OID4VCI routes are documented in the generated API reference.

The OID4VCI profile is registry-backed and issuer initiated. Its only wallet-facing grant is pre-authorized code. It uses EdDSA did:jwk holder proof and EdDSA or ES256 issuer signing. The identity provider’s authorization code remains internal to Notary. There is no public nonce route, response next nonce, source-free issuance, ES256 holder proof, EUDI, HAIP, PAR, DPoP, or wallet-attestation profile.

Authentication

Registry Notary runs in static-credential mode or OIDC mode:

Static credentials: The client presents either an x-api-key token or an Authorization: Bearer token. Notary fingerprints the presented token and compares it (constant-time) against sha256:<...> values loaded from environment variables at startup. Each credential carries a scopes list, and per-claim scope requirements are enforced before evaluation.
OIDC: Notary delegates token verification to Registry Platform OIDC primitives (issuer, JWKS URI, audiences, algorithms, scope mapping) and still owns the scopes its claim routes require.

For the exact configuration, see the operator configuration reference.

Disclosure profiles

Notary controls what a caller receives through three disclosure levels (value, predicate, redacted), each governed by default and allowed settings in the claim definition. For a full explanation of how the levels interact and the downgrade strategies, see Evidence issuance, end to end.

Credential issuance

Notary issues SD-JWT VC credentials:

Token type dc+sd-jwt, with issuer signing configured as EdDSA (Ed25519) or ES256 (P-256).
The issuer key comes from the configured signing provider; its public JWK is published at GET /.well-known/evidence/jwks.json.
Individual claim fields are wrapped in SD-JWT disclosures with SHA-256 digests for selective disclosure.

Issuance and holder-proof helpers come from Registry Platform; Notary owns the credential profile, claim selection, and route workflow. Notary does not emit W3C Verifiable Credentials Data Model envelopes: the format is SD-JWT, not a W3C VC JSON object.

Both issuance routes require a newly stored, non-delegated evaluation with exact compiler pins and normalized unique Relay execution records for every selected root’s registry-backed dependency closure. Each pin has a deterministic SHA-256 binding to its execution and exact claim provenance; issuance recomputes it before signer access. This detects partial stored-record mutation but is not a keyed authenticity anchor. Private execution ids are stored only for evaluations whose roots share a validated credential profile. Legacy, source-free, and delegated evaluations remain renderable but are nonissuable and must be re-evaluated.

CCCEV rendering

The render route can return CCCEV-shaped JSON-LD when the caller requests application/ld+json; profile="cccev". The output includes an @context with the cccev, dcterms, foaf, time, and xsd namespaces, evidence nodes typed as cccev:Evidence, and CCCEV properties (cccev:isProvidedBy, cccev:supportsRequirement, cccev:supportsValue, cccev:validityPeriod, cccev:isConformantTo). Conformance against CCCEV 2.00 is not claimed; consume the output by parsing the @graph for cccev:Evidence nodes.

Evidence inputs

Notary accepts two evidence modes:

Registry-backed claims consume a compiler-pinned Registry Relay consultation. The contract fixes the consultation profile, inputs, purpose, and expected result shape before Relay performs source work.
Source-free and self-attested claims use only the configured request inputs and caller policy.

Registry Relay owns all registry source origins, credentials, HTTP execution, script adaptation, protocol helpers, snapshots, and minimized typed consultation outputs. Notary does not configure or execute direct registry source connectors.

What the specification does not cover

Plugin rule type: The Plugin rule variant is declared in config but has no implementation at the pinned commit.
Holder binding: OID4VCI supports EdDSA did:jwk holder proof only.
Demo helpers: Generated workflow helpers are examples, not production replay-protection profiles. Add freshness, expiry, or nonce checks before copying a helper into a production workflow.
Admin reload: the standalone router returns 501 with registry.admin.capability.not_supported; key and configuration changes require a service restart.
Admin posture: GET /admin/v1/posture returns the shared versioned operations observation. RS-OP-POSTURE defines its envelope, tiers, and consumer rules.

Behavior the schema cannot express

Audit events: Every evaluated request emits an EvidenceAuditEvent in a Registry Platform audit envelope to a configured sink (stdout, file/jsonl, or syslog).