Thinking in IHV Model
Before you read any integration guide, get the mental model right. Every credential flow in TCS involves at least two of three roles plus two governance services, with a small set of API calls per role. Issuance touches Issuer + Holder; presentation touches Holder + Verifier; only the full lifecycle covers all three. Once you can name the role you are playing, picking the right endpoint becomes obvious.
The triangle
Section titled “The triangle”A verifiable credential lives inside a triangle of three actors:
- The Issuer signs a credential and hands it to the holder.
- The Holder stores it in a wallet and chooses when and what to present.
- The Verifier receives a presentation and confirms two things: was this credential issued by a trusted issuer? and is the person presenting it the rightful holder?
The arrow from Verifier back to Issuer is dotted because the verifier never calls the issuer at presentation time. Trust is established out-of-band through the Trust Registry — that is what makes the model scale.
The two governance services
Section titled “The two governance services”Sitting underneath all three roles are two services that hold the trust fabric together:
| Service | Question it answers | Used by |
|---|---|---|
| Trust Registry | ”Is this issuer / verifier allowed to operate?” | All three roles |
| Schema Registry | ”What does a valid credential of this type look like?” | Issuer (writes), Verifier (reads) |
Without these two services, an issuer is just signing JSON and a verifier has no way to decide whether a signature it sees should be trusted. With them, the system has a published source of truth — both for who and what.
How TCS services map to roles
Section titled “How TCS services map to roles”The mapping depends on which operating mode you run. In TCS’s default custodial mode, your backend orchestrates all three IHV roles by calling TCS services — including Holder Service, a hosted wallet exposed as a REST API. In non-custodial mode, the Holder is an external wallet on the user’s device that you do not call.
| Role | Custodial mode (default) | Non-Custodial mode |
|---|---|---|
| Issuer | Trust Registry → Schema Registry → Credential Issuer | Same |
| Holder | Holder Service — your backend calls /v1/user/*, /v1/did/*, /v1/oid4vci/*, /v1/oid4vp/*, /v1/vc/* on behalf of each end user | The user’s own wallet app — you don’t call it; you deliver an offer or request via QR / deep link |
| Verifier | Trust Registry → Verifier Service | Same |
If you are unsure which mode you need, pick custodial — Holder Service is a general-purpose cloud wallet management API and almost always saves work. See Custodial vs Non-Custodial Mode for the full comparison, including how holder keys are handled (your secret manager, never TCS — by design).
The first useful question after picking a mode is which roles your product plays. A KYC platform usually plays Issuer + Verifier. A bank issuing a credential to its own customers plays Issuer + Holder (custodial). A government portal might play Verifier only.
Flow 1 — Get a Credential
Section titled “Flow 1 — Get a Credential”This is the issuance path: an organisation issues a credential to an end user.
Walkthrough:
- Register — Issuer registers in the Trust Registry once and receives an API key. (Out-of-band onboarding step.) See Trust & Schemas.
- Define / pick a schema — Issuer chooses a credential type from the Schema Registry, or registers a new one. The schema’s identifier is its VCT (Verifiable Credential Type) — e.g.
TuringCerts_Standard_Credential_v2_sd_jwt— and appears in the issued credential’svctfield. See Schema Reference. - Issue an offer — Issuer’s backend posts the holder’s data to the Credential Issuer service. TCS returns an offer URI.
- Exchange code for token — Holder’s wallet exchanges the pre-authorized code (embedded in the offer) for an access token at the Authorization Server.
- Receive the credential — Holder’s wallet presents a JWT proof and receives a signed SD-JWT credential. It now lives in the wallet.
End-to-end runnable example: Quick Start. Integration depth: Issuing Credentials.
Flow 2 — Present and Verify a Credential
Section titled “Flow 2 — Present and Verify a Credential”This is the verification path: a service asks the holder to prove something, and the holder responds.
Walkthrough:
- Register — Verifier registers in the Trust Registry once.
- Define the request — Verifier’s backend builds a presentation request: which claims are required, which credential types are accepted, which issuers are trusted. The Verifier Service returns a deep link / QR.
- Holder presents — Wallet shows the request to the user, the user picks claims to disclose, the wallet signs a key-binding JWT, and submits the presentation. The Verifier Service returns the verification result.
The verifier only needs to handle two API calls. All cryptographic checks (issuer signature, key binding, expiry, revocation) happen inside the Verifier Service.
Integration depth: Verifying Credentials.
How to read the rest of the docs
Section titled “How to read the rest of the docs”Once you know your roles and your mode, every remaining page in the docs is either a sequence of API calls in your role or a concept you can defer until you need it.