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?
- 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.
- 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.
- 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.
- 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ır | Tamga (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 yetkileri | aynı |
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ğdabaseUrlhttps://issuer.tamga.network,slugkurumunuzun kayıtlı adıdır; API anahtarını kurum kaydından sonra Kurum Konsolu verir.
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ırsa429). - 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,expvejti'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_policyalanı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 varsainfo_uriverin; 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
| Kod | Ne der |
|---|---|
| SPEC-CRED-0003 S5 | iptal listesi, değişiklik olmasa da sabit aralıkta yayınlanır |
| SPEC-CRED-0003 S6 | aralık dışı ("acil") yayın yapılmaz; iptalin etkisi bir sonraki yayındadır |
| SPEC-CRED-0003 S8 | iptal listesinin adresi opaktır; yıl, bölüm, kohort kodlamaz |
| DP1 | kişisel veri ve belge içeriği güven altyapısına yazılmaz |