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. Registry-backed claims use a combined deployment in which Notary calls Registry Relay. 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.

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, signing algorithm EdDSA (Ed25519).
The issuer key is sourced from an environment variable (an OKP Ed25519 JWK); the public key 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.

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: did:jwk is the only supported proof-of-possession binding method.
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.

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).