Institution Source Endpoint

The lookup endpoint an institution exposes so that the hosted issuer can read credential data at issuance time.

Example — you choose the URL; it is configured for your institution on the hosted issuer.

https://sis.example.edu/tamga

Authentication

Bearer (tamga-source-request+jwt)

Definition

OpenAPI 3.1 file · Guide

Implemented by the institution, not by Tamga (ADR-0020, authentic source at the institution). Tamga's hosted issuer calls it and never stores the response. Two operations share one URL and are selected by the op claim of the signed request:

• lookup — the person started the request from the wallet and presented a Tamga identity attestation. Tamga sends the matching keys (national identification number + date of birth). Return the matching subject or 404.
• fetch — Tamga already knows your opaque subject reference (identity-bound offer, credential issuance, credential refresh). Return the current record or 404 (the person is no longer in your records).

Privacy. Return only the fields needed for the requested vct. Do not log the matching keys. Errors other than 404 make Tamga answer the wallet with temporarily_unavailable; no credential is issued.

Endpoints

Endpoint	Description
POST /	Look up or fetch a subject record

Authentication

Bearer (tamga-source-request+jwt)

Not a header: the body carries a short-lived JWT (typ: tamga-source-request+jwt, ES256, lifetime 60 s) signed with the access key Tamga uses for your institution. Verify it with the certificate in the x5c header and check that this certificate is listed for Tamga's hosted issuer in the Tamga signed trust list; check that aud equals your endpoint URL, check exp, and reject a repeated jti. Serve only over TLS.

Source

The single operation.

Look up or fetch a subject record

POST/

The body carries a signed request; its payload is SourceRequestClaims (below).

Authentication Bearer (tamga-source-request+jwt)

Request body

application/json

Field	Type	Description
request required	string	Compact JWS; payload is SourceRequestClaims.

Responses

Status	Description
200	Record found.
401	Request signature, audience, lifetime or replay check failed.
404	No matching record. Body may be {"subject": null}.
503	Temporarily unavailable. Tamga issues nothing and the person retries later.

Example

Request · curl

curl -X POST "https://sis.example.edu/tamga/" \
  -H "Content-Type: application/json" \
  -d '{"request":"eyJhbGciOiJFUzI1NiIsInR5cCI6InRhbWdhLXNvdXJjZS1yZXF1ZXN0K2p3dCIsIng1YyI6WyIuLi4iXX0.eyJvcCI6ImZldGNoIn0.sig"}'

Response · 200

{
  "subject": {
    "id": "…",
    "student_no": "…",
    "family_name": "…",
    "given_name": "…",
    "birth_date": "2026-10-09",
    "programme_title_tr": "…",
    "study_level": 0,
    "enrollment_year": 0,
    "student_status": "ACTIVE"
  }
}

Objects

SourceRequestClaims

Payload of the signed request.

Field	Type	Description
op required	string	One of: lookup · fetch
iss required	string	The hosted issuer's client identifier — x509_hash: + base64url(SHA-256(its access certificate)) (HAIP 1.0).
aud required	string	Your endpoint URL.
iat required	integer
exp required	integer	iat + 60
jti required	string
vct required	string	Credential type being issued, e.g. urn:tamga:edu:DiplomaCredential:1.
match	object	Present when op = lookup.
match.personal_administrative_number required	string
match.birth_date required	string (date)
subject_ref	string	Present when op = fetch. Your opaque identifier returned earlier as SubjectRecord.id.

SubjectRecord

Education profile (student and diploma credentials). id is your opaque, stable subject reference; Tamga keeps only this value (for revocation and refresh). Other profiles are added per credential type.

Field	Type	Description
id required	string
student_no required	string
family_name required	string
given_name required	string
birth_date required	string (date)
personal_administrative_number	string	Optional; used only for matching, never written into education credentials.
programme_title_tr required	string
programme_title_en	string
faculty_tr	string
isced_f_code	string | null
study_level required	integer	EQF/ISCED level
enrollment_year required	integer
student_status required	string	One of: ACTIVE · ON_LEAVE
expected_graduation_year	integer
programme_credit_points	number	Programme workload in ECTS (EU proof of enrolment, EUHEPOE). Optional.
enrollment_date	string (date)	Date of enrolment (EU proof of enrolment, EUHEPOE). Optional; enrollment_year stays required.
graduate	object	Present only for graduates; required for DiplomaCredential.
graduate.qualification_tr required	string
graduate.qualification_en	string
graduate.eqf_level required	integer
graduate.awarding_date required	string (date)
graduate.grade	string
graduate.thesis_title_tr	string
graduate.mode_of_study	string	One of: FULL_TIME · PART_TIME · DISTANCE · BLENDED

---

Import the machine-readable definition into any OpenAPI tool to generate a client or send test requests: institution-source.openapi.yaml.