Zero-knowledge proofs let APIs verify claims without exposing raw PII. Build an exchange flow with nullifiers, scopes, and proof checks. Read now.
Why APIs Need Verifiable Claims
Most APIs treat identity and eligibility as data to collect: age, account status, membership tier, residency. That model forces the client to send raw personal information and forces the server to store or process it. Zero-knowledge proofs reverse the contract. The client proves a statement about private data; the server only checks that the statement is true and that the proof was produced for this interaction. Raw PII never has to cross the wire or land in application logs.
A verifiable API therefore authenticates claims, not documents. The claim might be “this user is over the age threshold,” “this wallet holds a required credential,” or “this session is entitled to a scoped action.” The proof carries the claim; the server never needs the underlying attribute values to accept or reject the request.
Scopes: Bound the Statement the Proof Must Satisfy
Start by defining scopes as explicit, machine-checkable predicates. A scope names what is being asserted and under which policy: which attribute, which threshold or membership set, and which audience (your API, this environment, this product surface). Encode the scope as a public input to the circuit or proof system so the verifier can reject proofs that target a different statement.
Keep scopes small and stable. Broad scopes (“full identity verified”) invite over-collection and hard-to-audit circuits. Narrow scopes (“eligible for feature X under policy Y”) map cleanly to authorization checks and make rotation easier when policies change. Document each scope’s public inputs, required private witnesses, and failure modes so clients and auditors share one definition of success.
Nullifiers: Stop Replay Without Tracking Users
A proof that is valid forever is also valid for reuse. Nullifiers fix that. Derive a nullifier from a secret known only to the prover (for example a credential nullifier key) and from public context such as the scope and a challenge or epoch. The prover includes the nullifier in the public inputs; the server records it after a successful check and rejects later requests that present the same nullifier for that scope.
Choose nullifier granularity with intent. Per-request nullifiers block double-spend of a single action. Per-epoch nullifiers allow one use within a time window without continuous user identifiers. Avoid nullifiers that collapse to a stable global user id; that recreates linkable tracking while still calling the design “privacy-preserving.” Store only the nullifier and metadata needed for revocation and rate limits—not the proof’s private witnesses.
Exchange Flow and Proof Checks
A practical request path looks like this:
- Client requests a challenge or session binding (nonce, expiry, scope id, and verifier public parameters).
- Client builds the witness from local credentials and private attributes, then generates a proof for the scoped statement with public inputs: scope, challenge, nullifier, and any non-sensitive outputs the API needs.
- Client POSTs the proof and public inputs to the verify endpoint; no raw PII fields accompany the call.
- Server validates proof format, checks the challenge has not expired, verifies the cryptographic proof against the expected verification key, confirms the scope matches the route, and checks the nullifier is unused for that scope.
- On success, server marks the nullifier consumed, issues a short-lived access token or continues the business action, and returns a decision that does not echo private attributes.
Fail closed on every step: bad proofs, wrong scope, expired challenge, or known nullifier all map to a generic denial where possible, with internal metrics for circuit and key-version errors. Version verification keys and scope ids so you can roll circuits without accepting proofs for retired policies. Treat proof generation cost and latency as product constraints: offer clear client guidance on when to prove offline, how long challenges last, and which scopes a given credential can satisfy. Done this way, the API verifies eligibility and uniqueness without ever holding the raw personal data that classical identity flows demand.