Tamga Verify API

Web sitenizden ya da servisinizden kişiden belge isteyin, doğrulanmış sonucu alın.

Gerçek ağ: https://verify.tamga.network
Sandbox (deneme ağı): https://verify.sandbox.tamga.network
Kimlik doğrulama: Bearer (tamga-rp+jwt) ya da X-Tamga-Status-Token başlık
Tanım: OpenAPI 3.1 dosyası · Rehber

Tamga Verify, Tamga Network'ün barındırılan doğrulayıcısıdır (ADR-0017). Tarayıcı tarafı @tamga-network/verifier/web; barındırılan doğrulayıcı olmadan sunucuda doğrulama @tamga-network/verifier.

Akış. Sunucunuz bir politika (hangi belge, hangi alanlar) için sunum açar → sayfanız QR kodu ya da "Cüzdanında aç" bağlantısını gösterir ve status_token ile durumu sorar → durum DONE olunca sunucunuz sonucu ve bir kez onaylanan değerleri okur.

Gizlilik. Sonuç ve değerler yalnızca sunumu açan doğrulayıcıya gider. Değerler bir kez okunabilir ve en geç sonuçtan 5 dakika sonra silinir. Tarayıcı yalnızca durumu görür, değerleri hiç görmez.

Sonuçlar. ACCEPTED, REJECTED (başarısız adımla) ya da INDETERMINATE ("şu an denetlenemedi" — asla geçersiz sayılmaz).

Uç noktalar

Uç nokta	Açıklama
POST `/presentations`	Sunum isteği aç
GET `/presentations/{id}`	Durumu ya da doğrulama sonucunu al
GET `/presentations/{id}/claims`	Onaylanan değerleri oku (bir kez)
GET `/presentations/{id}/qr.png`	QR kodu görüntüsünü al
GET `/policies`	Politikaları listele
GET `/tamga-verifier.js`	Sayfa kitini yükle

Kimlik doğrulama

Bearer (tamga-rp+jwt)

Authorization: Bearer <RP beyanı> — Tamga güven listesinde kayıtlı erişim sertifikanızın özel anahtarıyla imzalanmış kısa ömürlü bir JWS (typ: tamga-rp+jwt, ES256). x5c başlığı sertifikayı taşır; içerik { iss: <client_id'niz>, aud: "https://verify.tamga.network", iat, exp ≤ iat + 60, jti }. Paylaşılan gizli anahtar yoktur; jti tek kullanımlıktır. Yardımcı: @tamga-network/verifier içindeki createRpAssertion().

X-Tamga-Status-Token başlık

Tarayıcı için yalnız durum jetonu (?st= olarak da kabul edilir). Durumu gösterir, değerleri asla.

Sunumlar

Belge isteyin ve sonucu okuyun.

Sunum isteği aç

POST/presentations

Politika için imzalı bir OpenID4VP isteği oluşturur. Politika kayıtlı kapsamınızın içinde olmalıdır (değilse 400 policy_exceeds_scope). JSON almak için Accept: application/json gönderin; göndermezseniz doğrulayıcı kendi bekleme sayfasına yönlendirir.

Kimlik doğrulama Bearer (tamga-rp+jwt)

Parametreler

Ad	Yer	Tür	Açıklama
`Accept` zorunlu	başlık	string	JSON yanıt isteyin. Her zaman `application/json`

İstek gövdesi

application/json

Alan	Tür	Açıklama
`policy_id` zorunlu	string	`GET /policies` listesinden bir politika, ör. `site-signup`, `age-over-18-mdoc`.
`dc_api_origin`	string (uri)	İsteğe bağlı. Sunum tarayıcının Digital Credentials API'siyle yanıtlanacaksa sayfanın kökeni (`https://…`, yol yok). İstek bu kökene bağlanır (`expected_origins`).

Yanıtlar

Durum	Açıklama
200	Sunum açıldı. Döner: StartedPresentation
400	`unknown_policy`, `policy_exceeds_scope` (politika kayıtlı kapsamınızdan fazlasını istiyor; `detail` neyi olduğunu listeler) ya da `invalid_request` (geçersiz `dc_api_origin`). Döner: Error
401	`invalid_rp_assertion` — RP beyanının süresi dolmuş, tekrar kullanılmış ya da kayıtlı ve etkin bir doğrulayıcı tarafından imzalanmamış. Döner: Error
429	`rate_limited` — çok fazla istek. `Retry-After` başlığındaki saniye kadar bekleyip yeniden deneyin. İstemci adresi saklanmaz ve günlüğe yazılmaz; cüzdanın çağırdığı `/vp/response` ve kapıların `/terminal/verify` uçlarında da aynı koruma vardır. Döner: Error Başlıklar: `Retry-After`

Örnek

İstek · curlYanıt · 200

bash

curl -X POST "https://verify.tamga.network/presentations" \
  -H "Authorization: Bearer $RP_ASSERTION" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"policy_id":"site-signup"}'

json

{
  "presentation_id": "prs_Q2x0dVJmNkp3",
  "request_uri": "https://verify.tamga.network/vp/req/prs_Q2x0dVJmNkp3",
  "qr_payload": "openid4vp://?client_id=x509_hash%3A…&request_uri=https%3A%2F%2Fverify.tamga.network%2Fvp%2Freq%2Fprs_Q2x0dVJmNkp3",
  "expires_at": "2026-10-09T12:05:00Z",
  "status_token": "9VdB0qXr7mYk2LwPq1sZ3A"
}

Durumu ya da doğrulama sonucunu al

GET/presentations/{id}

RP beyanınızla: doğrulama sonucunun tamamı (cüzdan yanıtlayana kadar {"state": "PENDING"}). Yalnız durum jetonuyla (?st= ya da X-Tamga-Status-Token, Authorization yok): tarayıcı için durum; değer ve ad içermez.

Kimlik doğrulama Bearer (tamga-rp+jwt) ya da X-Tamga-Status-Token başlık

Parametreler

Ad	Yer	Tür	Açıklama
`id` zorunlu	yol	string	`createPresentation` yanıtındaki `presentation_id`.
`st`	sorgu	string	`createPresentation` yanıtındaki durum jetonu; tarayıcı için.

Yanıtlar

Durum	Açıklama
200	Durum (`PENDING`), tarayıcı durumu ya da sonucun tamamı. Döner: VerificationResult ya da BrowserStatus ya da Pending
401	`invalid_rp_assertion`. Döner: Error
404	`not_found` — bilinmeyen sunum ya da sizin değil (varlığı açığa vurulmaz). Döner: Error

Örnek

İstek · curlYanıt · 200

bash

curl "https://verify.tamga.network/presentations/prs_Q2x0dVJmNkp3" \
  -H "Authorization: Bearer $RP_ASSERTION"

json

{
  "verification_id": "vrf_Q2x0dVJmNkp3",
  "outcome": "ACCEPTED",
  "failed_step": "…",
  "failed_reason": "…",
  "indeterminate_reason": "SCHEMA_UNREACHABLE",
  "spec_version": "…",
  "sdk_version": "…",
  "checks_performed": [
    "T0",
    "A1",
    "A2",
    "B1",
    "C1",
    "D1",
    "E1"
  ],
  "checks_skipped": [],
  "issuer": {
    "issuer_id": "…",
    "state_code": "TR",
    "legal_name": "…",
    "category": "…",
    "assurance": "…",
    "class": "PUB"
  },
  "schema": {
    "schema_id": "…",
    "vct": "urn:tamga:id:IdentityAttestation:1",
    "status": "…"
  },
  "disclosed_claims": [
    "given_name",
    "family_name"
  ],
  "status": {
    "value": "VALID",
    "list_version": 0,
    "token_age_sec": 0,
    "reason": "…"
  },
  "freshness": {
    "trust_source": "list",
    "trust_version": 0,
    "trust_age_sec": 0
  },
  "evaluated_at": "2026-10-09T12:00:00Z"
}

Onaylanan değerleri oku (bir kez)

GET/presentations/{id}/claims

Kişinin onayladığı değerleri döndürür. Bir kez ve en geç sonuçtan 5 dakika sonrasına kadar okunabilir.

Kimlik doğrulama Bearer (tamga-rp+jwt)

Parametreler

Ad	Yer	Tür	Açıklama
`id` zorunlu	yol	string	`createPresentation` yanıtındaki `presentation_id`.

Yanıtlar

Durum	Açıklama
200	Değerler; sunum beklerken `null`.
404	`not_found` — bilinmeyen sunum ya da sizin değil.
410	`claims_gone` — değerler zaten okundu ya da süresi doldu.

Örnek

İstek · curlYanıt · 200

bash

curl "https://verify.tamga.network/presentations/prs_Q2x0dVJmNkp3/claims" \
  -H "Authorization: Bearer $RP_ASSERTION"

json

{
  "claims": {
    "given_name": "Ayşe",
    "family_name": "Yılmaz",
    "pseudonym": "ps_7Qm…"
  }
}

QR kodu görüntüsünü al

GET/presentations/{id}/qr.png

qr_payload bağlantısının PNG'si (440 px); doğrudan <img> içine konabilir.

Kimlik doğrulama Yok — herkese açık

Parametreler

Ad	Yer	Tür	Açıklama
`id` zorunlu	yol	string	`createPresentation` yanıtındaki `presentation_id`.

Yanıtlar

Durum	Açıklama
200	PNG görüntü.
404	Bilinmeyen sunum.

Örnek

İstek · curl

bash

curl "https://verify.tamga.network/presentations/prs_Q2x0dVJmNkp3/qr.png"

Politikalar

Neler istenebilir.

Politikaları listele

GET/policies

Bu doğrulayıcının isteyebildiği politikalar. Kişisel veri içermez.

Kimlik doğrulama Yok — herkese açık

Yanıtlar

Durum	Açıklama
200	Politika özetleri. Döner: PolicySummary

Örnek

İstek · curlYanıt · 200

bash

curl "https://verify.tamga.network/policies"

json

[
  {
    "policy_id": "age-over-18-zk",
    "purpose": "Over-18 check with a zero-knowledge proof — yes/no only, nothing else",
    "purpose_localized": {
      "en-US": "Over-18 check with a zero-knowledge proof — yes/no only, nothing else",
      "tr-TR": "Sıfır bilgi ispatıyla 18 yaş üstü doğrulaması — yalnızca evet/hayır, başka hiçbir şey"
    },
    "vct_values": [
      "urn:tamga:id:IdentityAttestation:1"
    ],
    "claims": [
      "age_over_18"
    ],
    "proximity": false,
    "format": "mso_mdoc_zk"
  }
]

Sayfa kiti

Tarayıcı tarafı dosyaları.

Sayfa kitini yükle

GET/tamga-verifier.js

@tamga-network/verifier/web paketinin tarayıcı dosyası (QR kod, "Cüzdanında aç" düğmesi, durum sorgusu, Digital Credentials API). 5 dakika önbellekte tutulur.

Kimlik doğrulama Yok — herkese açık

Yanıtlar

Durum	Açıklama
200	JavaScript.

Örnek

İstek · curl

bash

curl "https://verify.tamga.network/tamga-verifier.js"

Nesneler

StartedPresentation

Alan	Tür	Açıklama
`presentation_id` zorunlu	string
`request_uri` zorunlu	string (uri)	Cüzdanın imzalı isteği aldığı adres.
`qr_payload` zorunlu	string	`openid4vp://…` bağlantısı — masaüstünde QR kod, telefonda düğme olarak gösterin.
`expires_at` zorunlu	string (date-time)
`status_token` zorunlu	string	Tarayıcıya yalnız bunu verin.
`dc_api_request`	object	`dc_api_origin` gönderildiyse gelir — `navigator.credentials.get({ digital })` girdisi.
`dc_api_request.protocol`	string	Her zaman `openid4vp-v1-signed`
`dc_api_request.data`	object
`dc_api_request.data.request`	string	İmzalı istek nesnesi (JWS).

Pending

Cüzdan henüz yanıtlamadı.

Alan	Tür	Açıklama
`state`	string	Her zaman `PENDING`

BrowserStatus

Tarayıcının durum jetonuyla gördüğü — değer yok, ad yok.

Alan	Tür	Açıklama
`state`	string	Değerler: `PENDING` · `DONE`
`outcome`	string	Değerler: `ACCEPTED` · `REJECTED` · `INDETERMINATE`
`failed_reason`	string \| null
`indeterminate_reason`	string \| null

VerificationResult

Sonucun tamamı; yalnız sunumu açan doğrulayıcıya.

Alan	Tür	Açıklama
`verification_id`	string
`outcome`	string	`INDETERMINATE` "şu an denetlenemedi" demektir — asla geçersiz saymayın. Değerler: `ACCEPTED` · `REJECTED` · `INDETERMINATE`
`failed_step`	string \| null	`REJECTED` ise doğrulama hattında ilk başarısız adım (T0, A1…E3, P1).
`failed_reason`	string \| null
`indeterminate_reason`	string \| null	Değerler: `SCHEMA_UNREACHABLE` · `STATUS_UNREACHABLE` · `STATUS_STALE` · `CHAIN_UNREACHABLE` · `INDEXER_STALE` · `SDK_VERSION_MISMATCH`
`spec_version`	string	Doğrulama şartnamesi sürümü.
`sdk_version`	string	Doğrulayıcı paket sürümü.
`checks_performed`	array<string>
`checks_skipped`	array<string>
`issuer`	object \| null	Belgeyi veren kurum (güven listesinden).
`issuer.issuer_id`	string
`issuer.state_code`	string
`issuer.legal_name`	string
`issuer.category`	string
`issuer.assurance`	string
`issuer.class`	string	Değerler: `PUB` · `QUALIFIED` · `EAA`
`schema`	object \| null
`schema.schema_id`	string
`schema.vct`	string
`schema.status`	string
`disclosed_claims`	array<string>	Açılan alanların adları (değerler `/claims` ile).
`status`	object	Belgenin iptal durumu.
`status.value`	string	Değerler: `VALID` · `INVALID` · `SUSPENDED` · `NOT_APPLICABLE` · `UNKNOWN`
`status.list_version`	integer \| null
`status.token_age_sec`	integer \| null
`status.reason`	string \| null	Durumun bu değeri neden aldığı (kendiliğinden anlaşılmıyorsa) — ör. sıfır bilgi ispatlı sunumda `NOT_APPLICABLE`; bu sunum iptal indeksini açmaz (ADR-0032; belge kısa ömürlüdür). Kabul edilip edilmeyeceğine politika karar verir; edilmezse sonuç `INDETERMINATE` olur. Kişisel veri içermez.
`freshness`	object	Kullanılan güven verisinin tazeliği.
`freshness.trust_source`	string	Değerler: `list` · `chain`
`freshness.trust_version`	integer
`freshness.trust_age_sec`	integer
`evaluated_at`	string (date-time)

PolicySummary

Alan	Tür	Açıklama
`policy_id`	string
`purpose`	string	Amaç (İngilizce).
`purpose_localized`	object	Dil etiketine göre amaç (`en-US`, `tr-TR`).
`vct_values`	array<string>
`claims`	array<string>	İstenen alanlar.
`proximity`	boolean	Politika ayrıca geçiş kartı verir.
`format`	string	`mso_mdoc_zk` = mdoc üzerinde sıfır bilgi ispatı (ADR-0032). İspatı üretemeyen cüzdan klasik `mso_mdoc` politikasını kullanır (ör. `age-over-18-mdoc`). Değerler: `dc+sd-jwt` · `mso_mdoc` · `mso_mdoc_zk`

Error

Alan	Tür	Açıklama
`error`	string
`error_description`	string
`detail`	array<string>	`policy_exceeds_scope` ile birlikte: kapsamınızı aşan kısımlar.

Makine okur tanımı herhangi bir OpenAPI aracına aktararak istemci üretebilir ya da deneme isteği gönderebilirsiniz: hosted-verifier-api.openapi.yaml.

Tamga Verify API ​

Uç noktalar ​

Kimlik doğrulama ​

Sunumlar ​

Sunum isteği aç ​

Parametreler ​

İstek gövdesi ​

Yanıtlar ​

Örnek ​

Durumu ya da doğrulama sonucunu al ​

Parametreler ​

Yanıtlar ​

Örnek ​

Onaylanan değerleri oku (bir kez) ​

Parametreler ​

Yanıtlar ​

Örnek ​

QR kodu görüntüsünü al ​

Parametreler ​

Yanıtlar ​

Örnek ​

Politikalar ​

Politikaları listele ​

Yanıtlar ​

Örnek ​

Sayfa kiti ​

Sayfa kitini yükle ​

Yanıtlar ​

Örnek ​

Nesneler ​

StartedPresentation ​

Pending ​

BrowserStatus ​

VerificationResult ​

PolicySummary ​

Error ​

Tamga Verify API

Uç noktalar

Kimlik doğrulama

Sunumlar

Sunum isteği aç

Parametreler

İstek gövdesi

Yanıtlar

Örnek

Durumu ya da doğrulama sonucunu al

Parametreler

Yanıtlar

Örnek

Onaylanan değerleri oku (bir kez)

Parametreler

Yanıtlar

Örnek

QR kodu görüntüsünü al

Parametreler

Yanıtlar

Örnek

Politikalar

Politikaları listele

Yanıtlar

Örnek

Sayfa kiti

Sayfa kitini yükle

Yanıtlar

Örnek

Nesneler

StartedPresentation

Pending

BrowserStatus

VerificationResult

PolicySummary

Error