Registry authentication and topology

Outcome. Your Registry enforces exactly the access model you chose — private, open-publish, or curated — with per-user keys you can mint and revoke, and a topology you selected deliberately.

Prerequisites

• A running Registry (Registry quickstart).
• openssl (or an equivalent) to generate key material.

The two gates

Reads and writes are gated independently:

Goal	REGISTRY_REQUIRE_READ_API_KEY	REGISTRY_REQUIRE_WRITE_API_KEY
Private Registry (read- and write-authorized participants)	true	true
Open market (public discovery, write-authorized participants)	false	true
Fully public Registry	false	false

The example environment file ships with both gates on. Two operator secrets exist: REGISTRY_ADMIN_API_KEY (operator-only, mints and revokes keys) and REGISTRY_BOOTSTRAP_API_KEY (the shared bearer token participants use until per-user keys are minted). Generate both with openssl rand -hex 32.

Mint and revoke per-user keys

Warning

This request mints a per-user credential, and the 201 response is the only time the Registry returns the raw key — store it securely and do not log or share it; the Registry keeps only its hash. The REGISTRY_ADMIN_API_KEY bearer that authorizes this mint (and the revocation below) is an operator-only secret; protect it accordingly. This route manages per-user keys only — the shared REGISTRY_BOOTSTRAP_API_KEY comes from the Registry environment file and is not minted or revoked here.

curl -X POST "http://<REGISTRY_HOST>:8080/admin/api-keys" \
  -H "Authorization: Bearer <REGISTRY_ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "buyer-alice", "scope": "read"}'

scope is read for buyers and write for sellers (default read); a write key also satisfies read routes. The 201 response pairs the raw key with the numeric id you later revoke it by. Hand write-scoped keys only to sellers you intend to authorize, and revoke any key you no longer control.

Revoke by numeric ID, then list key metadata to verify revoked_at is set:

curl -i -X DELETE \
  "http://<REGISTRY_HOST>:8080/admin/api-keys/<key_id>" \
  -H "Authorization: Bearer <REGISTRY_ADMIN_API_KEY>"

curl -s "http://<REGISTRY_HOST>:8080/admin/api-keys" \
  -H "Authorization: Bearer <REGISTRY_ADMIN_API_KEY>" | jq

Successful revocation returns HTTP 204; repeating it is idempotent, while an unknown ID returns 404. Participants send Authorization: Bearer <api_key> on every request, configured through their [registry.auth] table — and the key must match the URL in [registry] urls exactly (scheme, host, port, no trailing slash), because a mismatch silently sends unauthenticated requests.

Publishing attribution is separate from API access

Bearer tokens control access to your Registry. Listing attribution is cryptographic and independent: publishes are EIP-191-signed, the publisher record is created from the signature, and mutations are owner-scoped to the publisher identity. Revoking a seller's write key stops new writes; it does not transfer or erase their published attribution. Signature recovery proves control of the signing key for that request, not a real-world identity, organization, capacity, availability, or performance.

Topology is yours

All of the pinned deployment shapes are valid (Roles and authority): public Registry over many storefronts, private curated Registry, a seller's own co-located Registry, buyers querying several Registries at once. Your filter-spec is equally yours — vocabulary is per Registry, so a curated operator can shrink the discovery surface and a general one can widen it. Co-location with a seller stack is deployment convenience and never changes the protocol role: a Registry stores and filters listings, and does not negotiate or settle.

For production shapes, the pinned repository ships Helm charts composing Registry, storefront, and provisioning services with independent persistence: Helm deployment artifacts — maintained deployment pathways at the pin, not evidence of a hosted or production service.

Verify

curl -sf http://<REGISTRY_HOST>:8080/health
curl -s http://<REGISTRY_HOST>:8080/filter-spec | jq

An ungated read of /listings on a read-gated Registry must return HTTP 401 — if it returns records, your gate is off.

Troubleshoot

• Mint returns 422 — name is required and must be non-empty; scope must be read or write.
• Admin routes return 401 — the server-side REGISTRY_ADMIN_API_KEY is missing or the bearer value does not match.
• A participant token still fails — make the [registry.auth] key and [registry] urls entry byte-for-byte identical, including scheme, port, and trailing-slash choice.

Next steps

• Give a read-scoped key to a buyer and run the Discovery and comparison checks.
• Give a write-scoped key only to an authorized seller and follow the Seller quickstart, replacing every Registry placeholder with this Registry's URL.

Source and revision

Auth flow and checks are synchronized in the Registry quickstart; discovery contracts live in the registry-discovery specification; the exact mint and revoke request models live in the Registry administration routes.