Skip to content
GUIDE-0003RehberYürürlüktesürüm 1.0.04 Kasım 2026

Kurum olarak belge vermek ​

Bu rehber, kişilerin cüzdanına belge vermek isteyen kurumların, yani belge verenlerin (issuer)Belgeyi imzalayıp veren kurum: üniversite, meslek kuruluşu, kamu kurumu ya da şirket., geliştiricileri içindir: üniversite (diploma, öğrenci belgesi), kamu kurumu ya da bilet satıcısı.

Ne zaman okunur: kurumunuz Tamga'ya katılmaya karar verdiğinde, entegrasyona başlamadan önce. Kavramlar için Belge verme; çalışan kod için GUIDE-0004 §3.

Nasıl çalışır? ​

  1. Kurumunuz bir belge teklifi (credential offer)Belge verenin cüzdanı bir belgeyi almaya çağırdığı ileti; genelde QR kod ya da bağlantı. oluşturur: "bu kişiye şu belgeyi vereceğiz". Teklif bir bağlantı ya da QR'dır.
  2. Kişi teklifi cüzdanıyla açar; cüzdan belgeyi (credential)Belge verenin imzaladığı ve kişinin cüzdanında duran dijital belge; kişi yalnız istenen alanları gösterir. OpenID4VCI (OpenID for Verifiable Credential Issuance)Belge verenin belgeyi cüzdana teslim ettiği protokol. ile kurumdan alır.
  3. Belge kurumunuzun anahtarıyla imzalanır ve kişinin cihazındaki anahtara bağlanır (holder bindingBelgeyi yalnız belge sahibinin cihazındaki bir anahtara bağlamak; kopyalanan belge gösterilemez.); başka bir cihazda işe yaramaz.
  4. Gerekirse belgeyi iptal (revocation)Bir belgenin süresi dolmadan geçersiz kılınması; belge veren bunu doğrulayıcıların denetlediği iptal listesinde işaretler. edersiniz ya da askıya alırsınız; doğrulayıcılar (verifier)Gösterilen belgeyi denetleyen taraf: imza, belge verenin güven listesindeki kaydı, durum ve politika. Relying party diye de anılır. bunu iptal listesinden (status list)Her belgenin tek bir konumu olduğu sıkıştırılmış, imzalı liste; geçerli, askıda ya da iptal olduğunu söyler. görür.

İki yol var:

Barındırılan servis (önerilen başlangıç)Kendi servisiniz
Kim çalıştırırTamga (issuer.tamga.network/<kurum>)siz
Kuracağınız@tamga-network/issuer/client (bağımlılıksız, fetch)@tamga-network/issuer (+ trust, schemas, sd-jwt)
İmza anahtarısizde: kurumunuzun HSM'i ya da uzaktan imza hizmetiniz (CSC API v2, ADR-0057); sandbox'ta test anahtarısizin
Güven listesi kaydıTamga operatörü: kurum kaydı, kategori (ör. EDUCATION, EVENTS — ADR-0014), şema yetkileriaynı

Barındırılan servis: istemci ​

Önce sandbox'ta deneyin. Aşağıdaki örnek, test ağındaki örnek bilet satıcısının (issuer.sandbox.tamga.network) adresini kullanır; sandbox'ın adresleri ve örnek kurumları GUIDE-0013'te. Gerçek ağda baseUrl https://issuer.tamga.network, slug kurumunuzun kayıtlı adıdır; API anahtarını kurum kaydından sonra Kurum Konsolu verir.

ts
import { createIssuerClient } from "@tamga-network/issuer/client";

const tamga = createIssuerClient({ baseUrl: "https://issuer.sandbox.tamga.network", slug: "example-events", apiKey: process.env.TAMGA_API_KEY! });

// Bilet sattınız → cüzdana teklif (bilette kişisel veri yok)
const sale = await tamga.sellTicket({ eventId: "EVT-2026-KONSER-01", ticketClass: "STANDARD" });
// sale.offer.deepLink → QR ya da "cüzdanda aç" bağlantısı
// sale.offer.txCode   → AYRI kanaldan (SMS, e-posta, kasa ekranı) — teklif bağlantısıyla aynı kanaldan GÖNDERMEYİN (S5)

// Kayıtlı kişiye belge — önerilen: kimliğe bağlı teklif (PIN yok; yalnız teklifin sahibi alabilir, ADR-0020)
const bound = await tamga.createBoundOffer({
  subjectId: "s-1001", // kendi sisteminizdeki opak kişi kimliği
  vct: "urn:tamga:edu:DiplomaCredential:1",
  bind: { personalAdministrativeNumber: tckn, birthDate: "2002-05-14" }, // Tamga yalnız anahtarlı özetini saklar
});
// bound.deepLink → kişiye KENDİ kanalınızla (e-posta, öğrenci portalı) iletin; 7 gün, tek kullanımlık

// Yedek: kimlik belgesi olmayan kişi için PIN'li teklif
const offer = await tamga.createOffer({ subjectId: "s-1001", vct: "urn:tamga:edu:StudentCredential:1" });

// İptal / askı / geri alma — etkisi bir sonraki sabit aralıklı yayında (S6)
await tamga.revoke(credentialId, "mezuniyet iptali");

Hatalar IssuerClientError (status + mesaj) olarak gelir. Anahtar yalnızca sunucuda tutulur; tarayıcıya konmaz.

Üç teklif türünden hangisi?

  • Kimliğe bağlı teklif (önerilen): kişi kimlik belgesini cüzdanda gösterir, Tamga onu teklifteki özetle eşler. PIN gerekmez.
  • PIN'li teklif: kimlik belgesi olmayan kişi için yedek yol. PIN teklif bağlantısıyla aynı kanaldan gönderilmez.
  • Bilet: kişisel veri taşımaz; kimlik istenmez.

API anahtarı ​

Tamga operatörü kurumunuz için kapsamlı bir anahtar üretir (tmg_<slug>_…; ör. yalnızca tickets:write + revocations:write) ve güvenli kanaldan bir kez iletir; sunucuda yalnızca özeti tutulur (ADR-0016).

  • Anahtar 90 gün geçerlidir. Döndürmek için yenisi üretilir, siz geçersiniz, eskisi iptal edilir (ikisi bir süre birlikte geçerlidir).
  • Çağrılar https://issuer.tamga.network/{slug}/api/v1/… adresine gider; anahtar başına dakikalık sınır vardır (aşılırsa 429).
  • Kapsamlar: offers:write, tickets:write, tickets:read, revocations:write. Pilot kurumlarında ek olarak mTLS istenebilir.

Belge bilgileri sizin sisteminizden: sorgu ucu ​

Yetkili kaynak (authentic source)Belgedeki bilginin asıl sahibi olan sistem; örneğin üniversitenin öğrenci bilgi sistemi. sizin sisteminizdir (ör. öğrenci bilgi sistemi). Tamga belge bilgilerini tutmaz; belge verildiği anda sisteminizin sorgu ucuna imzalı bir istekle sorar ve yanıtı saklamaz (ADR-0020). Sözleşme: Kurum sorgu ucu.

  • lookup: kişi cüzdandan kurumunuzu seçip kimliğini sunduğunda — T.C. kimlik no + doğum tarihiyle arama.
  • fetch: kimliğe bağlı teklifte, belge verilirken ve kopya yenilemede — sizin opak kişi kimliğinizle okuma.
  • İstek, Tamga'nın güven listesindeki (trust list)Bir ülkenin kök sertifikalarını, belge verenlerini ve kayıtlı relying party'lerini taşıyan imzalı liste. Bugün Tamga'da güven bu listelere dayanır; ortak defter sonra gelir. kaydında yer alan erişim sertifikasıyla (access certificate)Relying party'nin isteklerini imzaladığı X.509 sertifikası; client kimliği bu sertifikanın özetinden türetilir. imzalı 60 saniyelik bir JWT'dir; aud, exp ve jti'yi denetleyin.
  • Hazır başlangıç: açık kaynak örnek uç (GUIDE-0004 §5) bu denetimlerin tamamını yapar ve yalnız gereken alanları döndürür.
  • Her kayıtta programın 4 haneli ISCED-F kodu olmalıdır (yoksa belge verilmez, tahmini kod üretilmez — E11); diploma yalnız mezuniyet bilgisi olan kayda verilir. İkisi de eksikse teklif açılırken reddedilir.
  • Sorgu ucu bağlanınca Kurum Konsolu'nda Belge ver sekmesi açılır: personel kişinin referansıyla masada teklif açar (kimliğe bağlı ya da PIN'li). Ucu bağlamadan önce belge vermeyi sandbox'taki örnek kurumlarla deneyin (GUIDE-0013). Kurum Konsolu'nun örnek kaynağı yalnız sandbox ortamında açılır; gerçek ağda kapalıdır ve oraya gerçek kişi verisi girilmez.

Tamga API'sinin tamamı: Belge verme API'si.

Kişisel veri ve kimlik ​

  • Belge alanlarını yalnızca belge için kullanın; loglara, URL'ye, iptal listesine yazmayın.
  • Kişiyi kendi kaydınızla eşlemeniz gerekiyorsa (diploma, öğrenci belgesi) kimlik doğrulama (identity proofing)Belge verilmeden önce kişinin gerçekten o kişi olduğunun doğrulanması; örneğin kimlik kartı ve canlılık testiyle.Tamga kimlik belgesi ile yapılır: cüzdan kimlik belgesini sunar, Tamga bunu teklifteki özetle ya da sorgu ucunuzla (lookup) eşler. Kimlik sağlayıcısıyla doğrudan konuşmazsınız (ADR-0011).
  • Bilet gibi kişisel veri gerektirmeyen belgelerde kimlik istemeyin.

Paylaşım kuralı: belgeyi kimlere gösterilsin ​

Bir belge türünü yalnız izin verdiğiniz doğrulayıcılara gösterilmek üzere sınırlayabilirsiniz (gömülü açıklama politikası, ADR-0046). Örnek: diploma yalnız işe alım hizmetlerine; meslek belgesi yalnız sağlık kuruluşlarına.

  • Nerede durur: kural imzalı belge veren bilgilerinizde (Credential Issuer metadata) belge türünün credential_metadata.embedded_disclosure_policy alanında, değer olarak yayınlanır. Belgeye girmez, doğrulayıcıya gönderilmez.
  • Üç seçenek: none (kısıt yok) · authorized_relying_parties (yalnız listedekiler) · specific_roots_of_trust (yalnız listedeki güven köklerinden sertifika almış doğrulayıcılar). İzinli doğrulayıcı üç yoldan yazılabilir: kayıt kimliği ve isteğe bağlı hizmet (relying_parties: [{ "rp_id": "VATTR-…", "service_id": "hiring" }]), erişim sertifikasının konu adı (subject_dns, RFC 4514) ya da yetki türü (entitlements). Kuralı sade dille anlatan bir sayfanız varsa info_uri verin; cüzdan "Kuralı oku" bağlantısı gösterir.
  • Cüzdan ne yapar: kuralı belgeyi alırken saklar; belge gösterilirken doğrulayıcının kayıt sertifikasıyla, internete çıkmadan denetler. Doğrulayıcı izinli değilse ya da denetlenemezse (ör. yakın mesafede) kişiyi uyarır, varsayılan seçim "Paylaşma"dır; son kararı kişi verir.
  • Kural değişirse: eklemek, değiştirmek ya da kaldırmak o türün geçerli bütün belgelerini iptal eder (EP4) — cüzdanlar kuralı belgeyle birlikte alır. Kişiler belgeyi yeniden almalıdır; sessiz yenileme açıksa yeni kopyalar yeni kuralla gelir.
  • Barındırılan serviste: Kurum Konsolu → Paylaşım kuralları (yalnız yönetici). Kural yalnız iptal edilebilen kurum belgelerine (diploma, bilet) konabilir; kimlik ve iletişim belgelerine konmaz. Konsol, uygulamadan önce kaç belgenin iptal edileceğini gösterir ve onay ister.
  • Kendi servisinizde: issuerMetadata({ authorizedVcts: [{ vct, name, display, disclosurePolicy }] }) kuralı denetleyip yayınlar; disclosurePolicyDigest(policy) özetini belge kaydına yazın ve özet değişince belgeleri iptal edin.

Denemek için: GUIDE-0013'taki örnek üniversitenin diploması yalnız örnek doğrulayıcının işe alım hizmetine (hiring) sınırlıdır; "Mezunlar ağı" senaryosu aynı doğrulayıcının başka hizmetidir ve cüzdan orada uyarır.

Derinlik: kendi servisiniz ​

@tamga-network/issuer belge üretimini, OpenID4VCI sunucu yardımcılarını (teklif, tx_code, c_nonce, proof of possessionGösteren kişinin, belgenin bağlı olduğu özel anahtarı elinde tuttuğunun taze bir meydan okumayı imzalayarak kanıtlanması. doğrulaması), Token Status List yayıncısını ve çapa isteğini sağlar; protokol profili SPEC-PROTO-0001. Referans: Tamga'nın işlettiği belge verme servisi. Başlamadan önce Tamga ile kurum kaydı, şema yetkileri ve anahtar yönetimi (KMS/HSM) konuşulur.

Kurallar ​

KodNe der
SPEC-CRED-0003 S5iptal listesi, değişiklik olmasa da sabit aralıkta yayınlanır
SPEC-CRED-0003 S6aralık dışı ("acil") yayın yapılmaz; iptalin etkisi bir sonraki yayındadır
SPEC-CRED-0003 S8iptal listesinin adresi opaktır; yıl, bölüm, kohort kodlamaz
DP1kişisel veri ve belge içeriği güven altyapısına yazılmaz