Skip to content

Non-Custodial Mode

In non-custodial mode, the holder runs their own wallet (any standards-conformant OID4VCI / OID4VP wallet) and TCS only operates the issuance and verification edges. There is no Holder Service in this mode — the integration points are Credential Issuer and Verifier Service only.

If you do not yet know which mode you need, read Custodial vs Non-Custodial Mode first.

This page covers two things:

  1. The delta from custodial mode — what changes for the integrator.
  2. The wallet-protocol details (proof JWT, key-binding JWT, sd_hash) you need when integrating with an external wallet, building one, or debugging a presentation that the verifier rejects.

ConcernCustodial modeNon-Custodial mode
Wallet runtimeHolder Service (TCS-operated)User’s own wallet app
Key custodyIntegrator-managed in their secret manager (see Holder · Manage Wallets & Credentials § 5)User-managed (wallet keeps its own keys)
Credential storageHolder Service databaseUser’s device
Recovery on device lossRecoverable via Holder ServiceWallet-app dependent
Compliance scopeHolder Service is in scopeWallet vendor is in scope
Deployment topologyAll seven servicesSix services (no Holder Service)
  • Issuance API surface. You still call POST /v1/offers exactly as in Issuer · Issue Credential.
  • Verification API surface. You still call POST /v1/verifier/authorization-request and poll GET /v1/verifier/result/{session_id} exactly as in Verifier · Verify Credential.
  • Governance. Trust Registry and Schema Registry are required in both modes.
  • Standards conformance. Both modes implement OID4VCI v1, OID4VP v1, SD-JWT VC, and DPoP identically.

The mode decision is invisible to the issuer and verifier roles. They cannot tell — and should not need to know — which kind of wallet sits on the other side.

In non-custodial mode you do not call Holder Service:

  • /v1/user/*, /v1/did/*
  • /v1/oid4vci/* (Holder Service receive)
  • /v1/oid4vp/* (Holder Service presentation)
  • /v1/vc/*

Instead, you deliver deep_link (from offers) and authorization_request (from verifier requests) to the user’s wallet app via QR code, push notification, or universal link.

Wallets must support SD-JWT VC with the dc+sd-jwt format, the _sd selective-disclosure mechanism, and key binding via kb+jwt. HAIP-conformant wallets (e.g. EUDI Wallet) interoperate out of the box.

Wallets that only support W3C JWT-VC (vc+jwt) will not interoperate with TCS credentials.

If you deploy TCS yourself you can omit Holder Service; six services suffice:

ServiceRequired in non-custodial mode?
Authorization ServerYes
Credential IssuerYes
Verifier ServiceYes
Trust RegistryYes
Schema RegistryYes
SchedulerYes
Holder ServiceNo

The two modes can coexist on a single deployment for different tenants — non-custodial mode does not require a separate cluster.


The rest of this page is for engineers integrating with an external wallet or building one. If your wallet is conformant, you do not strictly need to know any of this — these are the wire details handled inside the wallet.

These details apply to OID4VCI v1 / OID4VP v1. Custodial-mode integrators do not need them — Holder Service handles all of this internally.

Rendering diagram...

The issuer delivers a credential offer URI:

openid-credential-offer://?credential_offer_uri=https://issuer.turingspace.co/v1/offers/a1b2c3d4-...

Fetch credential_offer_uri to get the offer JSON. The pre-authorized code is at grants["urn:ietf:params:oauth:grant-type:pre-authorized_code"]["pre-authorized_code"].

Terminal window
curl -X POST https://auth.turingspace.co/v1/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn:ietf:params:oauth:grant-type:pre-authorized_code\
&pre-authorized_code=SplxlOBeZQQYbYS6WxSbIA"

Response (no c_nonce):

{
"access_token": "eyJhbGciOiJFZERTQSJ9...",
"token_type": "Bearer",
"expires_in": 3600
}

The token endpoint may return token_type: "DPoP" and a DPoP-Nonce response header when DPoP is in use.

Transaction code (PIN). TCS does not support transaction codes. POST /v1/offers with require_transaction_code: true returns 400 invalid_request, so TCS offers never carry a tx_code object and the wallet never sends tx_code to POST /v1/token.

Terminal window
curl -X POST https://issuer.turingspace.co/v1/nonce

Response:

{
"c_nonce": "tZignsnFbp"
}

The nonce endpoint is on the credential issuer (not the authorization server). It is a public POST with no body — no Authorization header is needed for a standalone nonce. If you are using DPoP-bound tokens, send the access token in Authorization: DPoP <token> together with a DPoP proof to refresh the DPoP nonce simultaneously.

The response has no c_nonce_expires_in field (OID4VCI 1.0 Final §7). The c_nonce is HMAC-signed by the issuer (no DB write to issue it), single-use, and short-lived (300 s).

The proof JWT proves to the issuer that the wallet controls the binding key.

ClaimValue
issHolder’s DID or client identifier
audIssuer’s credential_issuer URL (from issuer metadata)
iatCurrent Unix timestamp
nonceThe c_nonce from Step 3
HeaderValue
algES256 or EdDSA
typopenid4vci-proof+jwt
jwk or kidSend one of them. If the header has both, the issuer uses jwk and ignores kid. Use jwk when the wallet holds a standalone keypair with no resolvable DID — embed the public key as a JWK in the header. Use kid with a DID URL in one of these DID methods: did:iota (the issuer resolves the DID document from the IOTA network, e.g. kid: "did:iota:testnet:0x...#key-1"), did:jwk (the key is inside the DID), or did:key (Ed25519 only, did:key:z6Mk...). A DID that cannot be resolved or a signature that does not verify returns 400 invalid_proof.

The /credential endpoint URL is published in issuer metadata as the credential_endpoint field — fetch GET /.well-known/openid-credential-issuer/{tenant} and read it from there. The path intentionally omits the /v1/ prefix so that issuers can publish a deployment-specific endpoint URL without coupling wallets to TCS’s internal versioning. The example below shows the value TCS publishes today.

Terminal window
curl -X POST https://issuer.turingspace.co/credential \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGci..." \
-d '{
"credential_configuration_id": "TuringCerts_Standard_Credential_v2_sd_jwt",
"proofs": { "jwt": ["eyJhbGciOiJFUzI1NiIs..."] }
}'

If the issuer rejects with invalid_nonce, the c_nonce either expired or has already been consumed. Re-run Step 3 to obtain a fresh one and rebuild the proof JWT — do not reuse the previous proof.

Response (200 OK):

{
"credentials": [
{ "credential": "eyJhbGciOiJFZERTQSIs...~<disclosure-1>~<disclosure-2>~..." }
]
}

Each credential is the full SD-JWT VC string in the form <issuer-jwt>~<disclosure-1>~<disclosure-2>~...~. Persist it together with the holder keypair — both are needed at presentation time.

Persist the SD-JWT string and the holder keypair together. Both are needed at presentation time — losing either makes the credential unusable.

Rendering diagram...
openid4vp://?client_id=https://verifier.example.com&request_uri=https://verifier.turingspace.co/v1/verifier/request/abc123

Fetch the JAR (a signed JWT) at request_uri, verify the signature, and decode it.

The JAR contains a dcql_query describing which credential types are accepted, which claims must be disclosed, and which issuers are trusted. See Verifier · DCQL Query Structure.

Step 3 — Match credentials and pick disclosures

Section titled “Step 3 — Match credentials and pick disclosures”

Match the request against credentials in your wallet. For each matching credential, choose the minimum set of disclosures that satisfies the request — selective disclosure means you only reveal what is required.

Take the stored SD-JWT and remove the disclosure entries the user chose not to reveal. Keep the issuer JWT and the chosen disclosures.

The key-binding JWT proves the presenter controls the bound key.

ClaimValue
audVerifier client_id (from the request)
nonceVerifier nonce (from the request)
iatCurrent Unix timestamp
sd_hashbase64url(SHA-256(utf8("<issuer-jwt>~<d1>~<d2>~...~"))) — hash the entire SD-JWT presentation string built in Step 4, including the trailing ~ but excluding the key-binding JWT itself. Encode the digest as base64url with no padding. A single byte of mismatch causes the verifier to reject the presentation with no diagnostic.
HeaderValue
algES256 or EdDSA
typkb+jwt

Send the presentation to response_uri from the request object as application/x-www-form-urlencoded. The body format depends on the response_mode in the request object.

direct_post: send vp_token and state.

Terminal window
curl -X POST https://verifier.turingspace.co/v1/verifier/presentation \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode 'vp_token={"<credential-query-id>":["<sd-jwt-presentation>~<kb-jwt>"]}' \
--data-urlencode "state=<state-from-request-object>"
FieldFormat
vp_tokenA JSON object. Each key is the id of a credential query in the DCQL query. Each value is a non-empty array of SD-JWT presentation strings (<sd-jwt-presentation>~<kb-jwt>).
stateRequired. Copy it back unchanged from the request object so the verifier can correlate the response with the session it created.
presentation_submissionOptional. The verifier does not use it.

direct_post.jwt: send only response, a JWE encrypted to the key in the request object’s client_metadata.jwks. The decrypted payload carries vp_token (same format as above) and state. Do not send state in the body; the verifier reads the session from the JWE header kid.

Errors:

StatuserrorWhen
400Bad RequestThe body has neither response nor both vp_token and state, or the response JWE cannot be decrypted.
400invalid_requeststate is unknown, the session expired or is not in progress, the JWE header has no usable kid, or the decrypted state does not match.
400invalid_vp_tokenvp_token is not a JSON object of non-empty string arrays, or a presentation fails a check (signature, key binding, nonce, audience, credential status).
422dcql_query_not_satisfiedThe presentations do not satisfy the DCQL query (for example a required credential or claim is missing).

When verification fails, the session moves to failed; the per-check reasons are available from the result endpoint.

Response (200 OK):

{
"redirect_uri": "https://verifier.example.com/callback?session_id=b2c3d4e5-..."
}

redirect_uri is present only if the verifier configured one. The verifier’s session moves to completed; the verifier client polls GET /v1/verifier/result/:sessionId for the verification outcome (see Verifier · Verify Credential § Step 3).

  • aud for the proof JWT must be the credential_issuer URL, not the credential endpoint. Issuer metadata defines this exactly.
  • aud for the key-binding JWT must be the client_id of the verifier. Not the verifier service URL.
  • DPoP proofs are single-use and nonce-bound. When the server returns a fresh DPoP-Nonce, build a new proof — do not reuse the previous one.
  • c_nonce is fetched from the credential issuer’s /v1/nonce, not from the token endpoint. Per OID4VCI 1.0 Final §7.
  • c_nonce and verifier nonce expire in 300 s. Build the JWT and submit immediately. On invalid_nonce, refetch /v1/nonce and rebuild the proof — do not reuse the previous one.
  • The SD-JWT presentation must end with ~ even after stripping disclosures, to indicate “no more disclosures follow before the key-binding JWT”.