Integration overview

This page is the conceptual layer between the step-by-step onboarding path and the full technical documentation. It describes the shapes of the interactions — enough to architect an integration before reading an API reference.

The request

A verification request is a structured message from your registered service to a user's wallet. Every request carries four things:

• Who is asking — your service's on-chain identity, displayed to the user by name. Unregistered askers cannot make requests.
• What is required — one of: a minimum tier (for example Standard), a specific proof (age-over, residency, score-range), or a specific verified claim.
• The scope involved — the data category the request touches, from the consent framework's scope model (for example veid.trust_score). Scopes are consented independently; a request cannot bundle.
• A purpose string — plain language, shown verbatim to the user. This becomes part of the consent record, so write it as if it will be audited: it will.

The response

If the user approves, you receive a signed result — never raw data. Responses come in three forms:

• Tier confirmation — the user's verification tier, signed by the network. You check it against your requirement and store the outcome.
• Pass/fail result — a boolean against the threshold you stated (for example, score meets your minimum), without the underlying value.
• Zero-knowledge presentation — a proof object for age-range, residency or score-range circuits. You verify it cryptographically; verification requires no call back to the user and reveals nothing beyond the statement proven.

Verifying a ZK presentation

Zero-knowledge presentations are verified against public parameters published for each circuit. Your integration checks that the proof is valid, that its public inputs match your request (the threshold you asked about, the commitment anchored at the user's verification), and that it is bound to your request rather than replayed from another. All three checks are local computation — fast, offline-capable, and deterministic. The circuits themselves (age range, residency, score range) are open source, so your security team can review exactly what a passing proof does and does not establish — the plain-English version is in the credentials and proofs catalogue.

Consent records and your obligations

Every response you receive is paired with a consent record: scope, purpose, optional expiry, timestamp. Two behaviours matter in your architecture. First, fail closed on revocation and expiry: a fresh request after either will be declined by the protocol, and your flows should treat that as a normal state — prompt for re-consent, do not error. Second, retain your receipts: consent receipts are your audit evidence that processing was permitted at the time it happened.

What has no API

There is deliberately no endpoint for document images, biometric data, unconsented claims, bulk queries, or a user's consent history beyond your own grants. If your design requires any of these, it does not fit this system — and, we would argue, it should be redesigned before it fits any system. The reasoning is set out in why centralised identity databases fail.