Skip to content
GUIDE-0002GuideIn forceversion 1.0.029 October 2026

Verify credentials on your server ​

This guide is for developers who want to verify Tamga credentialsA digital document signed by an issuer and held in the person's wallet; the person shows only the fields that are asked for. on their own server, without going through the hosted verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party.: hiring, campus access, age checks, ticket gates.

When to read: when you want credential values never to pass through an intermediary, or you want to run verification on your own infrastructure. For a faster start, use the hosted verifier: GUIDE-0001. Working code: GUIDE-0004 §2.

How it works ​

  1. Your server describes what it wants with a policy (e.g. "diploma: name, programme, graduation year") and produces a signed request. The request is shown as a QR code or a link; it contains no personal data.
  2. The person sees the request in the wallet and approves; the wallet sends the answer to your server, encrypted.
  3. Your server decrypts the answer and runs the verification pipeline: signature, trust listA signed list of a country's root certificates, issuers and registered relying parties. Today trust in Tamga rests on these lists; a shared ledger comes later., revocationWithdrawing a credential before it expires; the issuer marks it in a status list that verifiers check. status, validity period, holder bindingTying a credential to a key that only the holder's device has, so a copied credential cannot be presented. and policy.
  4. The result is one of three values: accepted, rejected, or "cannot be verified right now".

@tamga-network/verifier implements the whole pipeline (SPEC-API-0001, steps T0 + A–E). The reference verifier apps/verify (verify.tamga.network) uses the same library; every step below runs there.

Preparation ​

  1. Verifier registration. You have a verifier entry in the Tamga trust list: your permanent identifier is your domain name (dns_name), your client identifier has the form x509_hash:…A client identifier scheme from HAIP: the identifier is the base64url SHA-256 hash of the relying party's access certificate. (the list publisher computes it from your access certificateThe X.509 certificate a relying party signs its requests with; its client identifier is derived from this certificate's hash.), and your X.509 certificate and the scope of the fields you may ask for are registered too. If your request goes beyond that scope, the wallet refuses it.
  2. Trust source. Load the trust lists with @tamga-network/trust: loadTrustSourceFromDir(dist), or regular download + reload (guardedReload). Ask every trust question of TrustSource only.
  3. Prefetch the status lists. new PrefetchStatusCache() + a regular refresh(uris). Nothing goes over the network at the moment of verification. Reload the trust lists and the anchor log (fetchListTrustSource(…, { anchors: true })) regularly too — more often than the policy's freshness.max_anchor_lag_sec (default 3600 s), for example every 10 minutes. A verifier that loads the anchors only at start-up answers "could not verify" (STATUS_STALE, D5) for every credential after about an hour; a verifier that never loads them gives the same answer for every credential older than an hour. Working example: GUIDE-0004 §2 (refresh()).
  4. Your registration certificate. For each registered use the registrar publishes a registration certificateA signed statement from the registrar listing which fields a relying party may request and for what purpose (valid up to 12 months). (trust.tamga.network/wrprc/index.json → the item with your client_id and scope_id). Put it into every request (registrationCert): from packages 0.7.0 Tamga Wallet refuses a request without one (ADR-0026, ADR-0056). Working code: GUIDE-0004 §2.

Flow ​

ts
import { dcqlFromPolicy, createPresentationRequest, openPresentationResponse, responseKidOf, verifyPresentation,
         pemRpSigner, BranchRegistry, BranchSet, type Policy } from "@tamga-network/verifier";

const policy: Policy = { policy_id: "ise-alim", /* credentials, trust, freshness */ } as Policy;
const signer = await pemRpSigner(RP_KEY_PEM, RP_CERT_PEM); // client_id = x509_hash (from the certificate)
const registry = new BranchRegistry(); // one per process
// 1) open a presentation: shown as a QR code / deep link (no personal data; request_uri only)
const content = { signer, dcql: dcqlFromPolicy(policy), responseUri: "https://ornek.com.tr/vp/response",
  registrationCert: WRPRC_JWT }; // your use's registration certificate (step 4 above)
const req = await createPresentationRequest({ ...content, requestUriBase: "https://ornek.com.tr/vp/req" });
const branches = new BranchSet({ registry, presentationId: req.presentationId, expiresAt: req.expiresAt, content });
// 2) GET|POST /vp/req/:id — every fetch gets its own request object (fresh state, nonce, key; ADR-0067)
const f = await branches.fetch(walletNonce); // f.ok → respond with f.requestJwt
// 3) the wallet POSTs the encrypted response to response_uri → lock, decrypt, check again
const branch = branches.get(responseKidOf(jweBody)!.branchId!)!;
if (branches.begin(branch) !== "ok") throw new Error("busy or closed");
try {
  const opened = await openPresentationResponse(jweBody, req, content.responseUri, (id) => (id === branch.branchId ? branch : undefined));
  if (opened.kind !== "response" || !branches.isOpen(branch) || !branches.stateMatches(branch, opened.response.state)) throw new Error("rejected");
  // 4) verify (SD-JWT; for mdoc use format: "mso_mdoc" + responseUri)
  const { result, claims } = await verifyPresentation({ presentation: opened.response.vp_token["diploma"][0],
    aud: signer.clientId, nonce: branch.nonce, policy, policyCredentialId: "diploma", trust, statusCache, rootCertsDer,
    rp: trust.relyingParty(signer.clientId) });
  if (!result.checks_performed.includes("A6")) branches.failedAttempt(branch); // used up only after A6
  else if (!branches.tryConsume()) throw new Error("already answered"); // atomic acceptance: another branch's response was accepted first
} finally { branches.end(branch); }
// a decline (error + state): registry.byState(state)?.set.decline(…) — closes only that branch; answer 200, store no reason

Field names and signatures are defined in the package types; the full working example is apps/verify/src/routes/presentations.ts.

The client identifier has the x509_hash form (HAIP 1.0 §5); pemRpSigner(key, certificate) computes it from the certificate (ADR-0034). When you renew the certificate, the new certificate goes into the trust list first, then your server switches to it.

Reading the result ​

outcomeMeaningTell the user
ACCEPTEDevery step passeduse only the approved fields in claims
REJECTEDthe credential is invalid (signature, revocation, validity, binding, policy) — failed_step says where it failed"The credential was not accepted"
INDETERMINATEan infrastructure or freshness problem (e.g. STATUS_STALE in steps D2/D4/D5) — the credential is not bad"Cannot be verified right now, please try again"

checks_performed / checks_skipped may be kept for audit; do not keep personal data. The clock-skew tolerance is set with policy.freshness.max_clock_skew_sec (default 120 s).

Checklist ​

  • The nonceA random value used once; the verifier sends it and the wallet signs it, so an old presentation cannot be replayed. is single-use; the same response is never processed twice.
  • A success page is not proof. A browser that reached the redirect_uri has proven nothing; update the account or session only from the result your server recorded, and only for the session that opened that presentation. Acceptance must be a single conditional state change (pending → accepted / rejected): when two responses, or a response and a decline, arrive at the same presentation at once, only one of them writes the result. If you run several server instances, keep this state in shared storage with a conditional write. A response that does not reach the proof of possession (A6) must not close the presentation (SPEC-PROTO-0002 §10.1).
  • Every request_uri fetch should be its own branch (ADR-0067): with createRequestBranch, mint a fresh state, nonce and encryption key on each fetch; let a wallet decline close only its own branch and treat the presentation as declined only if it has a single branch. Otherwise anyone who sees the QR code can fetch the request object and break the real person's transaction with a forged decline. Open responses with openPresentationResponse.
  • The policy asks only for the fields it needs; for age a single mdocThe ISO/IEC 18013-5 mobile document format, encoded in CBOR; used for in-person presentation and for the mobile driving licence. field such as age_over_18 or age_over_15 is enough (the thresholds are a closed set: 15 and 18; ADR-0064). Tamga Verify also has the age-over-15-mdoc and age-over-15-zk policies.
  • Status listA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked. prefetching and trust list refreshing must be running. If they are not, results become INDETERMINATE — which is the correct behaviour.

In depth: age verification with a zero-knowledge proof (mso_mdoc_zk) ​

You can ask "is this person over 18?" without seeing the credential, the date of birth, the institution's signature or the device key (ADR-0032). The wallet produces a proof with Longfellow ZKAn open zero-knowledge proof system for mdoc credentials; Tamga uses it to prove facts such as age over 18 without revealing the birth date.; all you learn is "age_over_18 = true in the identity credential of a registered institution". Two presentations by the same person cannot be linked.

ts
const policy: Policy = {
  policy_id: "age-over-18-zk",
  purpose: { "en-US": "Over-18 check — yes/no only" },
  credentials: [{
    // ADR-0044: ZK only with the identity credential's short-lived ZK copy (≤ 24 hours, no revocation list)
    id: "identity", vct_values: ["urn:tamga:id:ShortLivedIdentityAttestation:1"],
    format: "mso_mdoc_zk", namespace: "tamga.id.1",
    required_claims: ["age_over_18"], constraints: { age_over_18: true }, // equality only
  }],
  trust: { ... }, freshness: { ... },
};
// Request: the accepted circuits come from the signed list (ZK2)
const dcql = dcqlFromPolicy(policy, { zkCircuits: trust.zkCircuits?.() ?? [] });
// Response: vp_token.identity[0] = base64url(DeviceResponse{ zkDocuments })
const out = await verifyPresentation({ presentation, format: "mso_mdoc_zk", responseUri, aud, nonce,
  policy, policyCredentialId: "identity", trust, statusCache, rootCertsDer, rp: trust.relyingParty(aud) });
  • Read the answer with isYes: isYes(out, "age_over_18") is true only for an accepted result whose value is exactly true; a rejected or indeterminate result never reads as "yes".
  • Verification runs on the bundled WebAssembly; no Rust or native build is needed. One verification takes about 3 s on a desktop.
  • A native backend for very high volume: from the packages/verifier/zk source, cargo build --release --locked --features native --bin tamga-zk-verify (Rust 1.98.1, Linux/macOS), then new NativeZkBackend({ binPath }) or, from the environment, zkBackendFromEnv() (TAMGA_ZK_NATIVE_BIN) → VerifyInput.zk. A verification takes about 0.2–0.3 s; if the binary does not respond, it falls back to WASM.
  • New step Z1: is the circuit in the signed list, was only the requested element disclosed, is the timestamp fresh, is the proof valid? The institution signature, the device signature and the validity are checked inside the proof (checks_skipped: A4–A7). No revocation status comes with it (status.value: NOT_APPLICABLE, the reason in status.reason). Only the identity credential's short-lived copy is presented with ZK (ADR-0044): it is valid for at most 24 hours and the copies of a revoked credential are not refreshed; because the proof binds the copy's type, the verifier sees that it is short-lived and expects no revocation check. Revocation takes effect for ZK within 24 hours at most; if you need to see revocation immediately, use the classic mso_mdoc policy.
  • accept_unrevocable_zk: only for a ZK presentation that is NOT a short-lived copy (unmarked). true knowingly accepts such a presentation whose revocation cannot be checked; with false or when the field is omitted (the default) an unmarked ZK presentation returns INDETERMINATE (step D1, STATUS_UNREACHABLE).
  • Fallback: if the wallet does not support ZK, your query will not match; ask the same question with the classic mso_mdoc policy (age-over-18-mdoc). Wallet side: @tamga-network/zk (Android native library ready, iOS pending); a wallet without a prover uses the classic path (ZK5).

Rules ​

CodeWhat it says
SPEC-API-0001 AP2INDETERMINATE is never put in the same bucket as REJECTED
SPEC-API-0001 AP3–AP4results and records carry no field values and no status index
SPEC-API-0001 AP6a request cannot exceed the scope of the verifier's registration
Single trust interfacetrust data is read only through TrustSource
SPEC-CRED-0003 S12no status list is fetched per verification; batch prefetching is used
SPEC-PROTO-0002 PV10the nonce is single-use
ADR-0032 ZK2, ZK5only circuits in the signed list are accepted; without ZK, the classic path