In brief
This document describes how an institution verifies, before issuing a credential, that a person really is who they claim to be (identity proofingChecking that a person really is who they claim to be before a credential is issued, for example with an ID card and a liveness check.). It is written for issuing institutions (issuersThe institution that signs and issues credentials: a university, a professional body, a public institution or a company.) and for developers who connect to an identity verification provider.
When to read
- First read the Issuance concept page and the GUIDE-0003 guide.
- How the credential is bound to the wallet is not covered here: SPEC-CRED-0002.
- For Tamga's identity credential service, go straight to §9.
Plain explanation
Every credential type requires a minimum assurance level (LoA (Level of Assurance)How much confidence can be placed in an identity or a credential; Tamga uses separate levels for proofing (T), issuer (I) and wallet (W).): for a student certificate, e-mail and SMS are enough; a diploma needs stronger verification (for example an identity card + liveness check + face match, or the institution's registration desk). The institution reaches this level before issuing the credential; if it cannot, it does not issue. Remote verification is performed by a licensed provider; the institution keeps only a short summary of the result, identity images are not stored and the level is not written into the credential. Until a state identity credential exists, Tamga's identity service performs this verification and gives the result to the wallet as a separate identity credential.
Scope
This specification covers identity proofing on the institution's side: how the question "is the person receiving this offer really the subject of the credential?" is answered before issuance. Out of scope: binding to the wallet (cnf/KB-JWT (Key Binding JWT)A short token the wallet signs with the credential's key at presentation time, proving the holder has the key. — SPEC-CRED-0002), face matching on the verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party. side (the RP (Relying Party)Short for relying party: the organisation that requests and verifies credentials.'s responsibility), and PID (Person Identification Data)The core identity data a state issues at the highest assurance level. Tamga does not take this role; its identity credential is not a PID. issuance (Tamga does not issue PID, BT8).
Principle (PM-ASSUR-0001; the eIDAS (electronic IDentification, Authentication and trust Services)The EU regulation on electronic identification and trust services; eIDAS 2.0 introduces the European Digital Identity Wallet. model): the holderThe person who keeps a credential in their wallet and decides whom to show it to. level is not written into the credentialA digital document signed by an issuer and held in the person's wallet; the person shows only the fields that are asked for.; a credential type carries a minimum level as a precondition; the institution reaches that level before issuance and writes the binding path into its audit record (SPEC-PROTO-0001/PR7).
1. Levels and paths
| Level | eIDAS LoA | ETSI TS 119 461 (D-ASSUR-2) | Path | Where |
|---|---|---|---|---|
| T0 | — | — | Device key + e-mail/phone OTP; no identity claim | Anonymous/pseudonym scenarios (not used in beta) |
| T1 | Low | Baseline | (a) e-mail offer + SMS tx_code over a different channel; (b) offer on the student information system screen (single factor); (c) bank micro-transfer / mobile line ownership | Issuer/portal |
| T2 | Substantial | Substantial (document + liveness or in person) | (a) Licensed remote identity verification (identity document OCR/NFC + liveness + face match) — "IDV provider" in this document; (b) offer on the student information system screen with MFA; (c) the institution's registration desk (in person, staff confirmation) | IDV provider / portal / desk |
| T3 | High | High | Signing a nonce with a qualified e-signature / mobile signature (from the initial stage on); PID in the state stage | Only authorization code or in person; forbidden with pre-authorized (ETSI TS 119 472-3 GEN-REQ-4.1) |
Type ↔ minimum level is set in the rulebooksA set of binding rules. The Tamga Rulebook holds the rules for all participants; each credential type has its own rulebook that branches from it.: Education Rulebook — student certificate T1, diploma T2 (FW-RB-0002 §4.4). If the institution cannot reach the level a type requires, it does not produce an offer (issuance stops; no guessing or upgrading).
2. Flow — where identity proofing sits in the issuance chain
Portal / SIS session (person) Issuer service
│ "Add my diploma to my wallet" │
├── type = Diploma → required level T2 ─────────▶│ current level? (session type, earlier proofing record ≤ 12 months)
│ │
│ ◀── if insufficient: start IDV session (T2a) ──┤ POST /v3/session → url
│ IDV provider page: document + selfie │
│ ──▶ completed (callback / webhook) ────────────▶│ decision → T level + record
│ ◀── offer (QR + tx_code) ──────────────────────┤ PR7: audit {path:"idv:<provider>", level:"T2", session_ref}
▼ ▼
Wallet OpenID4VCI (SPEC-PROTO-0001) — unchangedIdentity proofing finishes before the offer is produced; the offer itself and the tx_code rules do not change (PR1, PR3, DB-5). The result may be reused for the same person for 12 months (PROPOSAL); the assurance decay rules apply (PM-ASSUR-0001 §Decay).
3. Remote identity verification provider — general rules
| # | Rule |
|---|---|
| IP1 | The provider's result is evaluated only on the issuer's side; the wallet and the verifier do not talk to the provider. |
| IP2 | The issuer binds the provider session to its own subject: vendor_data = an opaque issuer-internal reference (a random token of the student record); the identity number, name and e-mail are not written into vendor_data. |
| IP3 | The expected identity (given name, family name, date of birth) may be given to the provider as expected_details; the provider performs the match; the issuer additionally compares the result with the source data (exact match of name + date of birth; a difference → Review). |
| IP4 | What the issuer's system keeps is a summary of the result: {provider, session_ref, level, decided_at, checks:[id_document, liveness, face_match], expires_at}. The document image, portrait, raw OCR data and video are not stored (FW-RB-0001 RB-AP-23). |
| IP5 | Retention on the provider's side is reduced to the minimum by contract; the privacy notice under the Turkish data protection law (KVKK) names the provider as a data processor. |
| IP6 | A webhook MUST be verified with its signature + timestamp; an unsigned or stale (> 300 s) webhook is rejected; deduplication by event_id. |
| IP7 | A webhook is only a trigger; the decision is always confirmed by fetching it from the provider's decision API (the webhook body is not trusted). |
| IP8 | "In Review" / "Declined" / "Expired" → no offer is produced; the person is not shown the provider's result but the "apply to the institution's registration desk" path. The reason for rejection is not passed to the person in the provider's wording. |
| IP9 | During a provider outage, diploma issuance stops (it is not downgraded to T1); the student certificate (T1) is not affected. |
| IP10 | The provider and the workflow identifier (workflow_id) are in the tenant configuration; the code is not provider-specific but works through an adapter interface (IdvProvider — §6). |
| IP11 | Logs: event type + session_ref + level; the person's name, document number and scores are not written (in the spirit of AP3). |
4. Reference provider — protocol mapping
The reference adapter uses the hosted verification flow of a remote identity verification provider. The provider's name, API addresses and setting names are in the operator's configuration document; this specification keeps only the provider-independent rules. If the provider changes, the adapter changes; the rules below do not.
| Step | Expected from the provider | Tamga usage |
|---|---|---|
| Authentication | API key | Tenant secret; in the operator's settings file, never in the repository |
| Create session | Workflow identifier, opaque customer data, return address, language, expected name/surname/date of birth | Customer data = opaque subject_ref; return = https://id.tamga.network/idv/return?r=<flow>; language tr; expected values name/surname/date of birth (IP3); extra metadata empty |
| Response | Session identifier and hosted verification address | Redirect to the address; session identifier = session_ref |
| Result | Decision endpoint: overall status, document, liveness and face match sub-checks, read name/surname/date of birth | Only the statuses + the name/surname/date-of-birth match result (boolean) are kept; image and video fields are read but not stored |
| Webhook | Signed event notification (HMAC-SHA256, timestamped) | Signature + timestamp (±300 s) verified; deduplication by event identifier; then confirmation from the decision endpoint (IP7). The endpoint returns 200 quickly, processing is queued |
| Workflow | Document + liveness + face match (+ NFC optional) | Tamga workflow: identity document + passive liveness + face match; AML off (purpose limitation); phone/e-mail off (T1 already via SMS) |
| Channel | Hosted address (redirect) | Today (list stage): hosted address (through the identity service id.tamga.network, desktop/mobile browser). An in-wallet SDK is not used (identity proofing is the institution's job, not the wallet's) |
| Test environment | The provider's test scenarios | Demo: with test scenarios; a fake adapter in e2e tests |
5. Result → level mapping
Provider status | Sub-checks | Name/surname/date-of-birth match | Tamga result |
|---|---|---|---|
Approved | id_verifications[].status = Approved ∧ liveness_checks[].status = Approved ∧ face_matches[].status = Approved | Exact match | T2 (path: "idv:<provider>") |
Approved | NFC Approved (chip document) | Exact | T2 (note: nfc: true; not T3 — T3 requires a signature) |
Approved | any of them not Approved | — | Insufficient → desk |
Approved | all Approved | No match | Review (staff decision; no automatic T2) |
In Review | — | — | Wait (≤ 24 h); then staff |
Declined, Expired, Kyc Expired, Abandoned | — | — | Insufficient; new session ≤ 3 attempts / 24 h |
Not Started, In Progress, Awaiting User, Resubmitted | — | — | In progress |
Document type restriction: expected_document_types = ["ID", "P"] (Turkish identity card, passport); issuing_state must be consistent with the institution's country or the student's nationality (if the nationality is not in the source data, the restriction is not applied).
6. Adapter interface (implementation contract)
interface IdvProvider {
readonly id: string; // provider identifier (from settings)
createSession(input: {
subjectRef: string; // opaque, not personal data
expected: { givenName: string; familyName: string; birthDate: string };
locale: "tr" | "en";
returnUrl: string;
}): Promise<{ sessionRef: string; url: string; expiresAt: number }>;
fetchDecision(sessionRef: string): Promise<IdvDecision>;
verifyWebhook(rawBody: Uint8Array, headers: Record<string, string>): { ok: boolean; eventId?: string; sessionRef?: string };
}
type IdvDecision =
| { state: "PENDING" }
| { state: "REVIEW" }
| { state: "FAILED"; reason: "declined" | "expired" | "abandoned" | "mismatch" | "incomplete" }
| { state: "PASSED"; level: "T2"; checks: { idDocument: true; liveness: true; faceMatch: true; nfc?: boolean }; decidedAt: number; expiresAt: number };Stored record (issuing service data/<slug>/state.json › proofing[subjectRef]): { provider, sessionRef, level, checks, decidedAt, expiresAt } — no other fields.
7. Error and boundary behaviour
| Situation | Behaviour |
|---|---|
| Provider 5xx / timeout | No diploma offer is produced; the person sees "identity verification is not possible right now" + the desk option |
| Invalid webhook signature | 400; event log entry; no action |
| Webhook did not arrive | The portal's return page queries the decision API (polling ≤ 10 min, 15 s interval) |
| Person fails 3 times | 24-hour lock; desk path |
| Result older than 12 months | Proof again (decay) |
| Registration desk path | Staff panel: "I have seen the identity" confirmation → path: "desk", level: T2, staff identity in the audit record |
8. Invariants
| # | Invariant |
|---|---|
| IDP1 | The holder's identity proofing level and path are not written into the credential; they are kept only in the issuer's audit record. |
| IDP2 | No offer is produced before the type's minimum level is reached; the level is not upgraded by guessing. |
| IDP3 | The IDV provider integration lives only in the Tamga identity attestation service (id.tamga.network, ADR-0011); institutional issuers, the wallet and the verifier do not talk to the provider. A wallet may read the document chip on the device that started the flow and relay the raw data unchanged to the identity service (ADR-0083); it does not verify chip data and makes no identity verification decision. |
| IDP4 | From the IDV result the issuer keeps only the summary record; document images, portraits, video and raw OCR data are not stored. |
| IDP5 | A webhook is not processed before its signature and timestamp are verified; the decision is always confirmed through the decision API. |
| IDP6 | No personal data is written into the vendor_data/metadata fields; only an opaque reference. |
| IDP7 | T3 is never granted on the basis of a remote IDV result; T3 requires a signature (qualified e-signature/mobile signature) or a PID and is not compatible with the pre-authorized flow. |
| IDP8 | A provider outage does not lower the level; issuance that needs it stops. |
| IDP9 | The identity service keeps the personal fields from the IDV result only until the moment of issuance; after issuance only the opaque subject_ref, the document number hash, the validity period and the status indices remain; images, selfies, video and raw OCR data are never stored at Tamga (K4). |
| IDP10 | The national identity number (personal_administrative_number) is carried only in the urn:tamga:id:IdentityAttestation:1 type and only as a selectively disclosable claim; it is written into no other type; the institution does not keep or log it after matching. |
| IDP11 | Before the identity attestation is issued, the privacy notice is shown and explicit consent is obtained; in a session without consent no IDV is started (access_denied). |
9. Tamga identity credential service
Until a state PID provider is appointed, remote identity verification is performed in Tamga's identity service and the result is given to the wallet as a credential. This credential is not a PID but a non-qualified EAA (Electronic Attestation of Attributes)The eIDAS term for a credential that attests attributes of a person, such as a degree or a membership. issued by Tamga as an issuer (category: IDENTITY, class: EAA, I2; no category claim in the credential — ADR-0022); pid_providers[] stays empty (TL8).
| Item | Value |
|---|---|
vct | urn:tamga:id:IdentityAttestation:1 (catalogue: id/IdentityAttestation/1.0.0) |
| Claims | given_name, family_name, birthdate, nationalities (array; each element disclosed separately), personal_administrative_number (Turkish ID number), document_type, document_number_hash (keyed SHA-256 / HMAC; 1.0.1), issuing_country, document_chip_verified, verification_method (remote-document-liveness-face | remote-nfc-liveness-face | in-person), age_over_18, age_over_15 (ADR-0064: ISO/IEC 18013-5 age_over_NN, closed set) — all selectively disclosable; no portrait; no LoA claim (PR7) |
| Validity / status | exp = issuance + 730 days; Token Status List (id.tamga.network/status/{listId}); when the same document is verified again, the previous one is revoked (K6) |
| Flow | Wallet: PAR (WUA) → browser /authorize (KVKK privacy notice + explicit consent) → provider (reference adapter; demo: FAKE, deviation S-15) → /idv/return decision query (the webhook is only a trigger, IDP5) → code → token (PKCE + WUA) → 10 copies |
| Use at an institution | The institution's issuing service requests a presentation of the identity credential when issuing (DCQL: Turkish ID number, date of birth, given name, family name), verifies T0 + A–E and matches it with its records (Turkish ID number + date of birth; a warning on normalised names) — SPEC-PROTO-0001 §11.2 |
| Level | Remote document + liveness + face = T2 (ETSI 119 461 Substantial); NFC chip = document_chip_verified: true only when passive authentication, the clone check (AA or CA) and the match of the live face with the chip photo all succeed (ADR-0083/CV2; technically High; legally T3 = qualified e-signature/mobile signature, IDP7) |
| Data controller | Tamga Network (K4): it keeps the record + hash; erasure request = §9.1 (the record is deleted, copies are revoked, deletion of the session at the provider is requested); the provider contract targets ≤ 30 days of image retention. Time-based purge (2026-10-28): an expired or revoked record is deleted automatically at the latest 30 days later together with its provider session, event-log rows after 365 days (TAMGA_ID_RECORD_RETENTION_DAYS, TAMGA_ID_EVENT_LOG_DAYS; the periods are a policy choice pending legal confirmation) |
| Webhook | A single target https://id.tamga.network/idv/webhook, event status.updated; there is no per-institution webhook |
| Age | No minimum age (2026-10-08, ADR-0043); the condition is identity verification with a valid identity document. A guardian-consent flow and the provider's limit for minors are open items |
Implementation: apps/id (operator repository) (settings, provider adapter, store, app); the IdvProvider interface is the same as in §6 (the reference provider adapter and FakeIdvProvider).
issuing_country(2026-10-11, project management decision). The field has its EU PID meaning: the country of the identity provider issuing the credential (Implementing Regulation (EU) 2026/1731). Today the Tamga identity service issues the credential itself on the basis of a scanned identity document, so the value reflects the country that issued the scanned identity document. When a state PID provider issues PID, the field carries the EU meaning and the documentation describes it the EU way. Code and schema do not change today.
9.1 The person's erasure request — POST /erasure
There is no user account; the request is proven by presenting the credentials the service has issued.
| Item | Value |
|---|---|
| Request | { "presentations": [ SD-JWT VC + KB-JWT, … ] } (1–20); no claim is disclosed; KB-JWT aud = the service address, nonce = POST /nonce (single use) |
| Verification | The signature is this service's (issuerId); possession through the KB-JWT cnf key; the record is found from the status list index; an expired or revoked credential is accepted too (while its record is held it is the person's data) |
| Effect | All copies of the record become INVALID; the record and the event log rows tied to it are deleted; deletion of the provider session is requested with privacy_erasure (IdvProvider.deleteSession; without the delete permission on the provider account the response is provider: "partial") |
| Response | `{ erased, rejected, provider: "deleted" |
| Log | Only counts (erasure: number of records, provider result); the record identifier and subject_ref are not written |
Only bits remain in the status listA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked. (no personal data). The pseudonymA stable account identifier the wallet derives separately for each website; two sites cannot link the same person. seed is not stored on the service side, so there is nothing to delete (PS2); if the person verifies their identity again, the same seed is derived again (ADR-0031).
9.2 App-store review — single-use review code (ADR-0033)
| Item | Value |
|---|---|
| Code | Generated by the operator (ops/review-code.ts create); 26 characters (130 bits), at most 14 days, single use, at most 3 active at the same time; only an HMAC digest in the database (review_codes; RV1) |
| Entry | The "Review code" field on the /authorize privacy notice page (POST /authorize/consent, review_code); if empty, the flow does not change |
| Effect | With a valid code, a trial verification only for that PAR (/review-idv/{session}, no request to the real provider); the person is a code-specific DEMO person (given name "DEMO", family name "App Reviewer") |
| Signature | A separate DEMO signer tamga-id-review (I1 in the trust list); the real signer is not used (RV2). The status list is the identity service's list |
| Credential | verification_method: review-demo, at most 7 days; the pseudonym seed comes from a separate key (it does not collide with real seeds) |
| Acceptance | It passes no policy that requires I2; only the Tamga Verify review-* policies (I1) |
| Limits | 5 failed attempts per PAR; service-wide, 20 failures in 10 minutes lock it for 15 minutes (IP addresses are not used); nginx rate limit on /authorize/consent |
| Off | If there is no DEMO key or the trust list does not know tamga-id-review, entering a code returns "not active" (503) |
| Log | review_code.accepted / .used (code identifier), .rejected (no detail); never the code or its digest |
9.3 Driving licence information — urn:tamga:id:DrivingLicenceAttestation:1 (ADR-0039)
The same service inspects the person's physical driving licence at the provider in a separate flow (accepting driving licences only) and issues the categories and dates on the card. It is not an official driving licence / mDL (DL1); the credential says so through the always-visible not_official_licence: true claim.
| Item | Value |
|---|---|
| Prerequisite | identity_presentation in the PAR: an SD-JWT VC + KB-JWT presentation of the Tamga identity credential in the wallet (aud = the service, nonce = POST /nonce, single use; given_name, family_name, birthdate and, when the credential has it, personal_administrative_number are disclosed — the number only for matching the card, ADR-0039 open question 1). The service checks the signature, that the record is active and that no other claim is disclosed; the flow record holds no personal attribute, only keyed match digests (HMAC; the key is a separate subkey derived from the document number digest key, never logged) and the id of the linked identity record |
| Flow | /authorize driving-licence-specific notice + explicit consent (no review code field) → the provider's driving licence flow (setting: separate flow id; without it the type is not announced) → /idv/return: is the document a driving licence, has the card expired, were categories read, do the name + date of birth on the card match the digest and, when the card carries an identity number (today TR, 11 digits), does the number digest match too (if the identity presentation did not disclose the number the credential is not issued; on a card without a number the name + date of birth match is enough) → code → token → 10 copies |
| Read from the provider | given name, family name, date of birth, issuing country, document number (only its HMAC digest is kept), the identity number on a TR card (in memory for matching only; never written to the credential or stored — DL2), issue/expiry dates, expired fact, per-category from/to dates (extra_fields.dl_class_code_<category>_from/_to). Never read: _notes fields, restriction codes, images, scores |
| Claims | given_name, family_name, birth_date, issuing_country, document_number_hash, driving_privileges[], licence_issue_date?, licence_expiry_date, verified_at, verification_method (remote-document-liveness-face), age_over_18, not_official_licence |
| Refusal | access_denied: not a driving licence · card expired · categories could not be read · all categories expired (expired categories are not written into the credential) · name or issuing country could not be read (no guessing) · does not match the identity · the linked identity is no longer active (revoked / re-issued / erased after the PAR; re-checked at /idv/return and /credential). No personal data in the description; only the reason code is logged. On every outcome without issuance (including provider decline/review) the provider session (card images, selfie) is deleted at once; sessions of abandoned flows are deleted during garbage collection before their id is forgotten |
| Validity / revocation | exp = min(card expiry, inspection + 1 year, expiry of the linked identity credential; DL3/DL5); SD-JWT VC only; status list; the record is linked to the identity record via parentId — revocation, re-issuance or erasure of the identity covers the linked credential; erasure also removes previously revoked linked records and their provider sessions (DL5) |
Security and privacy notes
- Identity proofing is purpose-limited: it is only a precondition of issuance; AML/PEP screening is off.
- The provider sees the person's document and face; this is stated clearly in the KVKK privacy notice and the choice of provider (data location, retention period, sub-processors) is bound by contract.
expected_detailsgives the provider the name/surname/date of birth (from the source data); this improves match quality but is a data disclosure; the alternative (matching the name returned by the provider at the institution) is defined in IP3 and left to the tenant's preference (PROPOSAL: do not share by default).- The demo uses the sandbox; no real personal data is processed (GT1).
Open questions
- Result reuse period (12 months) and attempt limits — the numbers are PROPOSALS.
- In-wallet IDV (SDK) never? It becomes unnecessary with the PID in the state stage; not for now.
- Provider diversity: a second adapter (a domestic provider / e-Devlet) — a vendor lock-in tripwire.
- Minors (ADR-0043): a guardian-consent flow (GDPR Art. 8; under Turkish law limited legal capacity below 18 — legal review) and the provider's own limit or condition for minors (not yet confirmed).
Related documents
PM-ASSUR-0001 · PM-ID-0001 · SPEC-PROTO-0001 · SPEC-CRED-0002 · SPEC-WALLET-0001 · FW-RB-0001 · FW-RB-0002 · ADR-0005 · ADR-0011 · ADR-0022
Status
In force — version 1.0.0 (2026-10-02).
Version note (2026-11-16, second). §9.3 driving licence attestation: implementation of the D-ID-8 note (2026-10-30, ADR-0039 open question 1, namesake risk) — the identity presentation also discloses personal_administrative_number when the credential has it; when the card carries an identity number (today TR) the keyed digest of the number must match as well, and without the disclosure the credential is not issued. The number is never written to the credential, stored or logged (DL2, PR14); the match digests use a separate subkey.
Version note (2026-11-16; approved by project management). ADR-0089 accepted: the identity record is the logical credential, its end is the administrative validity (730 days, bounded by ISSU_12c) and is carried in every copy as date_of_expiry; the technical validity of copies is at most 30 days and the wallet renews its copies silently by presenting a copy of this record with all claims disclosed — person fields are still not stored (IDP9), they stay in memory only for the lifetime of the renewal access token; the age attributes are recomputed on renewal. The mdoc copy of the identity credential is issued through a separate standard configuration. The identity service writes into the record the trust list id of the wallet provider that signed the WIA at issuance and, in the 6-hourly unit check, first looks at that provider's status in the list: REVOKED / RETIRED / not in the list → the record is revoked (wallet-provider-invalid); SUSPENDED → suspension (no new copy, no renewal, no ZK; it resumes when the suspension is lifted); the list cannot be read → no change (IR6).
Version note (2026-11-13, second; approved by project management). ADR-0083 K11 and CV7 changed: the code of the chip path is written now, but by default it sits behind a switch that is off — the identity service refuses to run on a server (live network and sandbox) while the switch is on, store builds of the wallet contain no chip reading, and the code runs only in local tests with fake document data. The chip path is opened in no environment before a favourable legal opinion. Interface names: /chip/read, /chip/submit, /chip/continue; PAR field chip_reader (icao9303). Today's behaviour is unchanged.
Version note (2026-11-13; approved by project management). ADR-0083 was accepted: IDP3 is narrowed (a wallet may read the document chip and relay the raw data unchanged to the identity service; it does not verify, decide or talk to the provider) and §9 states the condition for document_chip_verified: true (CV2). The flow and the open interface of the chip path (ADR-0083 K10) are added to this document with the implementation, which follows a legal opinion (CV7). Today's behaviour is unchanged: identity verification uses the document photo path.