Registry Notary API

Open Registry Notary API reference

The Redoc page above is generated from a pinned OpenAPI artifact. This page provides the narrative context the OpenAPI document does not carry: what surface is documented, which auth modes are declared, what disclosure profiles the specification exposes, and what is not in scope.

Evidence source: Registry Notary main commit 5b6be8a, generated after the v0.2.1 release and reviewed 2026-05-24.

Generate or refresh the artifact:

cargo run -p registry-notary-bin -- openapi > openapi/registry-notary.openapi.json

API surface

Registry Notary is a standalone Rust workspace for claim evaluation, disclosure policy, credential issuance, and audit. Registry Notary runs independently; it does not require Registry Relay to be running.

The pinned OpenAPI document is generated from the Registry Notary source and reports info.version as 0.2.1. The artifact includes the crate license metadata, protected API routes, public probe routes, the protected admin reload route mounted by the standalone router, and Redoc response examples for the high-value success and problem responses. Routes are implemented in crates/registry-notary-server/src/api.rs and crates/registry-notary-server/src/standalone.rs; the OpenAPI generator lives in crates/registry-notary-server/src/openapi.rs.

Method	Path	Purpose
GET	/healthz	Liveness probe, public
GET	/ready	Readiness probe, public
POST	/admin/reload	Admin-scoped no-op reload endpoint in the standalone router
GET	/openapi.json	Fetch the OpenAPI document
GET	/.well-known/evidence-service	Discover service capabilities and claim catalog
GET	/.well-known/evidence/jwks.json	Fetch the issuer JWKS
GET	/claims	List configured claim definitions
GET	/claims/{claim_id}	Get one claim definition
GET	/formats	List supported output formats
POST	/claims/evaluate	Evaluate claims for one subject
POST	/claims/batch-evaluate	Evaluate claims for multiple subjects
POST	/evidence/render	Render evidence in a requested format
POST	/credentials/issue	Issue a credential from an evaluation result

Default bind: 127.0.0.1:8081. The standalone demo config (demo/config/registry-notary.yaml) overrides this to 127.0.0.1:4255. The Registry Lab topology overrides it to 0.0.0.0:8080 inside the container (mapped to host ports 4321-4324).

Auth modes

Registry Notary supports either static credential mode or OIDC mode.

In static mode, two credential lists are checked in order:

API key: The client sends the token in x-api-key: <token>. The server fingerprints the presented token and compares it with sha256:<64 hex> values loaded from environment variables at startup.

curl -H "x-api-key: <your-key>" http://localhost:8081/claims

Bearer token: The client sends Authorization: Bearer <token>. The server parses the Bearer header with Registry Platform auth helpers, fingerprints the token, and performs a constant-time comparison.

curl -H "Authorization: Bearer <your-token>" http://localhost:8081/claims

Both static types are configured in auth.api_keys and auth.bearer_tokens in the Notary config file. Example:

auth:
  mode: api_key
  api_keys:
    - id: verifier
      hash_env: WITNESS_API_KEY_HASH
      scopes: ["civil:evaluate"]
  bearer_tokens:
    - id: verifier
      hash_env: WITNESS_BEARER_TOKEN_HASH
      scopes: ["civil:evaluate", "civil:issue"]

Each credential carries a scopes list. Per-claim scope requirements are enforced before evaluation proceeds.

In OIDC mode, auth.mode: oidc configures issuer, JWKS URI, audiences, accepted algorithms, scope mapping, and principal claim. Notary delegates token verification to Registry Platform OIDC primitives and still owns the scopes required by its claim routes.

Disclosure profiles

Registry Notary controls what a caller receives through a three-level disclosure system declared in crates/registry-notary-core/src/model.rs:

• Value: the full claim value is disclosed.
• Predicate: only the satisfaction result (true or false) is disclosed.
• Redacted: the value is fully hidden from the caller.

Each claim definition configures a default disclosure level and an allowed list. When a caller requests a level not in the allowed list, Notary applies a downgrade strategy: Deny returns an error, Default falls back to the claim’s configured default, and Redacted downgrades to the Redacted profile.

The POST /claims/evaluate and POST /credentials/issue routes expose this surface directly through the request body and response shape.

Credential issuance

When a caller requests POST /credentials/issue, Registry Notary issues an SD-JWT VC credential. The credential uses:

• Token type: dc+sd-jwt (the typ header).
• Signing algorithm: EdDSA (Ed25519).
• Key source: environment variable REGISTRY_NOTARY_ISSUER_JWK (OKP Ed25519 JWK with d and x components).
• Selective disclosure: individual claim fields are wrapped in SD-JWT disclosures with SHA-256 digests.
• Media type: application/dc+sd-jwt.

Reusable issuance and holder-proof helpers come from Registry Platform. Notary owns the credential profile config, claim selection, and route workflow.

The issuer public key is available at GET /.well-known/evidence/jwks.json.

Registry Notary does not emit W3C Verifiable Credentials Data Model envelopes. The credential format is SD-JWT, not a W3C VC JSON object.

CCCEV rendering

POST /evidence/render can return CCCEV-shaped JSON-LD when the caller requests application/ld+json; profile="cccev". The renderer in crates/registry-notary-server/src/runtime.rs produces:

• @context including the cccev, dcterms, foaf, time, and xsd namespaces.
• Evidence nodes typed as cccev:Evidence.
• CCCEV properties: cccev:isProvidedBy, cccev:supportsRequirement, cccev:supportsValue, cccev:validityPeriod, and cccev:isConformantTo.

Profile conformance against CCCEV 2.00 is not claimed. You can consume the rendered output as CCCEV-shaped JSON-LD: parse the @graph for cccev:Evidence nodes and read the listed properties to reconstruct what criteria a subject satisfies.

Source connectors

Registry Notary reads registry facts from external sources over HTTP. Two connector kinds are configured in source_connections:

Registry Data API connector: posts queries to {base_url}/{dataset}/{entity} on a Registry Relay instance. Authenticates with a bearer token per connection.

SP DCI connector: sends DCI-shaped search requests and parses the response using configured field paths. Default search path: /registry/sync/search. Default sender ID: registry-notary.

There is no generic file-based or database connector in Registry Notary. Source connectors must reach their targets over HTTP.

What the OpenAPI specification does not cover

Plugin rule type. The Plugin rule variant is declared in crates/registry-notary-core/src/config.rs but no implementation is present at the reviewed commit.

Proof-of-possession binding. did:jwk is the only supported holder binding method. Other DID methods are not supported.

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

Caution

Audit write failures surface as request errors, not as transparent log entries. If your audit sink is unavailable, callers will receive errors. Monitor the audit sink as part of your operational runbook.

Admin operations. POST /admin/reload exists but returns a no-op response in the standalone router. Key and configuration changes still require a service restart.