Issue credentials as an institution
This guide is for developers at institutions (issuersThe institution that signs and issues credentials: a university, a professional body, a public institution or a company.) that want to issue credentials to people's wallets: a university (diploma, student certificate), a public body or a ticket seller.
When to read: once your institution has decided to join Tamga, before you start the integration. For the ideas, see Issuance; for working code, GUIDE-0004 §3.
How it works
- Your institution creates an offer (a credential offer): "we will issue this credential to this person". The offer is a link or a QR code.
- The person opens the offer with the wallet; the wallet fetches 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. from the institution with OpenID4VCI (OpenID for Verifiable Credential Issuance)The protocol an issuer uses to deliver a credential to a wallet..
- The credential is signed with your institution's key and bound to the key on the person's device (holder bindingTying a credential to a key that only the holder's device has, so a copied credential cannot be presented.); it is useless on any other device.
- If needed, you revoke or suspend the credential (revocationWithdrawing a credential before it expires; the issuer marks it in a status list that verifiers check.); verifiersThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party. see this in the status listA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked..
There are two ways:
| Hosted service (the recommended start) | Your own service | |
|---|---|---|
| Who runs it | Tamga (issuer.tamga.network/<institution>) | you |
| What you install | @tamga-network/issuer/client (no dependencies, fetch) | @tamga-network/issuer (+ trust, schemas, sd-jwt) |
| Signing key | with you: your institution's HSM or your remote signing service (CSC API v2, ADR-0057); test key in the sandbox | yours |
| Trust list entry | the Tamga operator: institution entry, category (e.g. EDUCATION, EVENTS — ADR-0014), schema authorisations | the same |
Hosted service: the client
Try it in the sandbox first. The example below uses the address of the example ticket seller on the test network (
issuer.sandbox.tamga.network); the sandbox addresses and sample institutions are in GUIDE-0013. On the real networkbaseUrlishttps://issuer.tamga.networkandslugis your institution's registered name; the Institution Console gives you the API key after registration.
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! });
// You sold a ticket → an offer to the wallet (no personal data in the ticket)
const sale = await tamga.sellTicket({ eventId: "EVT-2026-KONSER-01", ticketClass: "STANDARD" });
// sale.offer.deepLink → a QR code or an "open in wallet" link
// sale.offer.txCode → over a SEPARATE channel (SMS, email, till screen) — NEVER over the same channel as the offer link (S5)
// A credential for a registered person — recommended: an identity-bound offer (no PIN; only the offer's owner can take it, ADR-0020)
const bound = await tamga.createBoundOffer({
subjectId: "s-1001", // the opaque person identifier in your own system
vct: "urn:tamga:edu:DiplomaCredential:1",
bind: { personalAdministrativeNumber: tckn, birthDate: "2002-05-14" }, // Tamga stores only a keyed digest
});
// bound.deepLink → send it to the person over YOUR OWN channel (email, student portal); 7 days, single use
// Fallback: an offer with a PIN for a person without an identity credential
const offer = await tamga.createOffer({ subjectId: "s-1001", vct: "urn:tamga:edu:StudentCredential:1" });
// Revoke / suspend / reinstate — takes effect in the next fixed-interval publication (S6)
await tamga.revoke(credentialId, "mezuniyet iptali");Errors arrive as IssuerClientError (status + message). The key is kept on the server only; never put it in a browser.
Which of the three offer types?
- Identity-bound offer (recommended): the person shows the identity credential in the wallet, and Tamga matches it with the digest in the offer. No PIN needed.
- Offer with a PIN: the fallback for a person without an identity credential. The PIN is never sent over the same channel as the offer link.
- Ticket: carries no personal data; no identity is asked for.
API key
The Tamga operator creates a scoped key for your institution (tmg_<slug>_…; e.g. only tickets:write + revocations:write) and hands it over once through a secure channel; the server keeps only its digest (ADR-0016).
- A key is valid for 90 days. To rotate it, a new key is created, you switch, and the old one is revoked (both are valid for a while).
- Calls go to
https://issuer.tamga.network/{slug}/api/v1/…; there is a per-minute limit per key (429if exceeded). - Scopes:
offers:write,tickets:write,tickets:read,revocations:write. Pilot institutions may also be asked for mTLS.
Credential data from your system: the source endpoint
The authentic sourceThe system that actually owns the data in a credential, for example a university's student information system. is your system (e.g. the student information system). Tamga does not keep credential data; at the moment of issuance it asks your system's source endpoint with a signed request and does not store the answer (ADR-0020). Contract: Institution source endpoint.
lookup: when the person picks your institution in the wallet and presents their identity — a search by national identity number + date of birth.fetch: for identity-bound offers, at issuance and when copies are renewed — a read with your opaque person identifier.- The request is a 60-second JWT signed with the access certificateThe X.509 certificate a relying party signs its requests with; its client identifier is derived from this certificate's hash. in Tamga's 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. entry; check
aud,expandjti. - A ready start: the open-source example endpoint (GUIDE-0004 §5) performs all of these checks and returns only the fields needed.
- Every record must carry the programme's 4-digit ISCED-F code (otherwise no credential is issued and no code is guessed — E11); a diploma is issued only for a record with graduation data. If either is missing, the offer is refused when it is created.
- Once the endpoint is connected, the Institution Console shows an Issue tab: staff create an offer at the desk with the person's reference (identity-bound or with a PIN). Before connecting the endpoint, try issuance with the sample institutions in the sandbox (GUIDE-0013). The Institution Console's sample source opens only in the sandbox environment; it is closed on the real network and real personal data is never entered there.
The whole Tamga API: Hosted issuer API.
Personal data and identity
- Use credential fields only for the credential; never write them to logs, URLs or the status list.
- If you need to match the person with your own record (diploma, student certificate), 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. uses the Tamga identity credential: the wallet presents the identity credential, and Tamga matches it with the digest in the offer or with your source endpoint (
lookup). You never talk to the identity verification provider directly (ADR-0011). - For credentials that need no personal data, such as tickets, do not ask for identity.
Sharing rules: who may see the credential
You can limit a credential type so that it is shown only to verifiers you allow (embedded disclosure policy, ADR-0046). Example: a diploma only for hiring services; a professional licence only for healthcare providers.
- Where it lives: the rule is published by value in your signed Credential Issuer metadata, in the credential type's
credential_metadata.embedded_disclosure_policy. It does not go into the credential and is not sent to verifiers. - Three options:
none(no restriction) ·authorized_relying_parties(only those listed) ·specific_roots_of_trust(only verifiers certified under the listed roots of trust). An allowed verifier can be written in three ways: its registration identifier and optional service (relying_parties: [{ "rp_id": "VATTR-…", "service_id": "hiring" }]), its access certificate subject name (subject_dns, RFC 4514) or an entitlement (entitlements). If you have a page explaining the rule in plain language, give it asinfo_uri; the wallet shows a "Read the rule" link. - What the wallet does: it stores the rule when it receives the credential and checks it at presentation against the verifier's registration certificate, without going online. If the verifier is not allowed or cannot be checked (for example in proximity), it warns the person and "Don't share" is the default; the person makes the final decision.
- If the rule changes: adding, changing or removing it revokes every valid credential of that type (EP4) — wallets receive the rule together with the credential. People must receive the credential again; with silent refresh on, new copies come with the new rule.
- On the hosted service: Institution Console → Sharing rules (admins only). A rule can be set only on institution credentials that can be revoked (diploma, ticket); never on identity or contact credentials. The console shows how many credentials will be revoked and asks for confirmation before applying.
- On your own service:
issuerMetadata({ authorizedVcts: [{ vct, name, display, disclosurePolicy }] })checks and publishes the rule; writedisclosurePolicyDigest(policy)into the credential record and revoke the credentials when the digest changes.
To try it: in the GUIDE-0013 the example university's diploma is limited to the sample verifier's hiring service (hiring); the "Alumni network" scenario is another service of the same verifier, and the wallet warns there.
In depth: your own service
@tamga-network/issuer provides credential creation, OpenID4VCI server helpers (offer, tx_code, c_nonce, proof of possession verification), the Token Status List publisher and the anchor request; the protocol profile is SPEC-PROTO-0001. Reference: the issuance service Tamga itself runs. Before you start, the institution registration, schema authorisations and key management (KMS/HSM) are agreed with Tamga.
Rules
| Code | What it says |
|---|---|
| SPEC-CRED-0003 S5 | the status list is published at a fixed interval, even without changes |
| SPEC-CRED-0003 S6 | no out-of-cycle ("urgent") publication; a revocation takes effect in the next publication |
| SPEC-CRED-0003 S8 | the status list address is opaque; it encodes no year, department or cohort |
| DP1 | no personal data or credential content is written to the trust infrastructure |