Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# Registry Notary API

> Narrative context for the Registry Notary OpenAPI reference: authentication, disclosure profiles, credential issuance, and documented limitations.

[Open the Registry Notary API operations](../notary/)

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`](https://github.com/registrystack/registry-stack) 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](../../../products/registry-notary/).

## 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](../../../products/registry-notary/operator-config-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](../../../explanation/evidence-issuance/).

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

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