跳到內容

Verifier · 驗證憑證

這頁是給 Verifier 角色:要求 holder 證明某件事的服務。從你的後端視角,驗證只有兩支 API 呼叫 — 建立 authorization request、然後讀結果。中間的事(取得簽妥的 request object、提示 user、組 VP token、提交)都在錢包端。


Rendering diagram...

你要實作的:

  1. 建立 request。 POST 你的 DCQL query 與 verifier 身分到 Verifier Service。
  2. 交付 request URI。
  3. Poll 結果。 監看 GET /v1/verifier/result/{session_id} 直到 session 變 completed。

VP token、SD-JWT 簽章、key-binding JWT 你都不用自己組或驗。Verifier Service 全做完,結果端點上會回 status(整體通過/失敗)與 check_results[](逐項檢查)。


Terminal window
curl -X POST https://verifier.turingspace.co/v1/verifier/authorization-request \
-H "X-API-Key: tcs_production_<your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"dcql_query": {
"credentials": [
{
"id": "identity_credential",
"format": "dc+sd-jwt",
"meta": {
"vct_values": ["https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2"]
},
"claims": [
{ "path": ["credentialName"] },
{ "path": ["issuedTime"] }
]
}
]
},
"verifier_private_key": "${VERIFIER_PRIVATE_KEY}",
"verifier_client_id": "did:iota:0xae72f18dc7b6af5b740edae8e4e0b2d3c9fb10a4e7d6c5b3a2f1e0d9c8b7a6f5",
"response_mode": "direct_post",
"expires_in": 300
}'

回應(201 Created):

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"request_uri": "https://verifier.turingspace.co/v1/verifier/request/b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"authorization_request": "openid4vp://?client_id=did%3Aiota%3A0xae72...&request_uri=https%3A%2F%2Fverifier.turingspace.co%2Fv1%2Fverifier%2Frequest%2Fb2c3d4e5-...",
"expires_at": "2026-03-26T00:05:00Z"
}
名稱型別必填說明
dcql_queryobject是你要哪些憑證、哪些 claim。詳見 DCQL Query Structure。
verifier_private_keystring僅 DIDBase64url 編碼的原生 Ed25519(32 bytes)。用來簽 JAR(request object)讓錢包驗「是誰在問」。verifier_client_id 是 DID 時必填;x509_san_dns: 與 x509_hash: client ID 不要帶。
verifier_client_idstring是Verifier 的 client ID,三種形式擇一:註冊在你帳號下的 DID(要搭配 verifier_private_key);x509_san_dns:<dns-name>,DNS 名稱必須是 server 設定的葉憑證 SAN 之一;或 x509_hash:<葉憑證 DER 的 base64url SHA-256>。兩種 x509_ 形式都用 server 設定的 X.509 材料簽 request object,不帶 verifier_private_key。錢包同意畫面上會顯示。
response_modestring否"direct_post"(預設,明文 server-to-server VP 交付)、"direct_post.jwt"(用 ECDH-ES 加密交付;TCS 會自動以 ephemeral 公鑰填入 client_metadata.jwks),或 "fragment"(可通過參數檢查,但 TCS 沒有能接收 fragment 回應的端點,session 不會完成 — 請用 "direct_post" 或 "direct_post.jwt")。
expires_innumber否Session TTL 秒數,60 到 3600(預設 300)。
client_metadataobject否client_name、logo_uri、policy_uri、tos_uri — 顯示在錢包同意畫面。vp_formats_supported — 你接受的憑證格式與演算法;省略時 TCS 送出 dc+sd-jwt 搭配 ES256 與 EdDSA。jwks — 回應加密用的公鑰;用 direct_post.jwt 時 TCS 會以 ephemeral 公鑰取代。
redirect_uristring否錢包提交後把 user redirect 去哪。Headless 流程可省略。
request_uri_methodstring否"get"(預設)或 "post"。設為 "post" 時,authorization_request 會帶 request_uri_method=post,錢包改用 HTTP POST 取 request object。
狀態原因
400Body 格式錯(缺欄位、dcql_query.credentials 為空、expires_in 不在 60–3600 等);DID client ID 沒帶 verifier_private_key、未註冊在你帳號下,或金鑰對不上;x509_ client ID 不在 server X.509 材料涵蓋範圍內
401X-API-Key 缺或無效

把 request 送到 holder 面前的方式取決於模式。

代表 user 把 authorization_request 傳給 Holder Service。Holder Service 會 fetch 簽妥的 request、提示 user、組 VP token、提交。詳見 Holder · 管理錢包與憑證 § 4。

Terminal window
curl -X POST https://holder.turingspace.co/v1/oid4vp/presentation \
-H "Authorization: Bearer ${HOLDER_USER_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"authorization_request_uri": "openid4vp://?client_id=...&request_uri=...",
"selected_credentials": [
{ "credential_id": "...", "query_id": "identity_credential",
"disclosed_claims": ["credentialName", "issuedTime"] }
],
"holder_did": "did:iota:testnet:0x7a8b...",
"private_key": "${HOLDER_PRIVATE_KEY}"
}'

回應(200 OK):

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

redirect_uri 只有 verifier 設了才會帶回 — deep-link user 過去完成 verifier 端後續流程。從 verifier 角度看 session 變 completed,verifier 整合用下面 Step 3 poll 結果。

把 authorization_request 渲染成 QR、或在 user 裝置上打開 deep link。錢包 App 跑剩下的 OID4VP,把 VP token 直接送到 Verifier Service 的 POST /v1/verifier/presentation — 這支請求的格式見非保管模式 § 第六步。


Terminal window
curl https://verifier.turingspace.co/v1/verifier/result/b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e \
-H "X-API-Key: tcs_production_<your-api-key>"

回應(200 OK,completed):

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "completed",
"created_at": "2026-04-01T00:00:00.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"verified_at": "2026-04-01T00:01:23.000Z",
"verification_mode": "fail_fast",
"check_results": [
{ "check": "credential_format", "status": "success", "reason_code": "credential_format_valid", "message": "The credential format is valid." },
{ "check": "signature", "status": "success", "reason_code": "signature_verified", "message": "The issuer signature was verified." },
{ "check": "key_binding", "status": "success", "reason_code": "key_binding_verified", "message": "The holder's proof of possession was verified." },
{ "check": "oid4vp_compliance", "status": "success", "reason_code": "oid4vp_request_valid", "message": "The verification request conforms to OID4VP." },
{ "check": "credential_status", "status": "skipped", "reason_code": "status_not_applicable", "message": "The credential carries no checkable revocation status reference." },
{ "check": "issuer_trust", "status": "skipped", "reason_code": "issuer_in_tr_approved", "message": "The issuer is in the trust registry and approved." },
{ "check": "issuer_governance", "status": "skipped", "reason_code": "partial_governance_coverage", "message": "The issuer is approved; governance coverage is partial." },
{ "check": "issuer_governance_vct_scope", "status": "skipped", "reason_code": "issuer_schema_scope_authorized", "message": "The issuer is registered to issue this credential type." },
{ "check": "schema_governance", "status": "skipped", "reason_code": "not_implemented", "message": "Trust layer check is not implemented yet." },
{ "check": "schema_version", "status": "skipped", "reason_code": "not_implemented", "message": "Trust layer check is not implemented yet." }
],
"presentation_metadata": {
"claims": {
"credentialName": "Bachelor of Science",
"issuedTime": "2026-01-15"
},
"credential_metadata": [
{
"issuer": "did:iota:testnet:0xabcdef...",
"credential_type": ["UniversityDegreeCredential"],
"issued_at": "2026-01-15T00:00:00.000Z",
"expires_at": "2027-01-15T00:00:00.000Z"
}
]
}
}

只有 check_results 裡沒有任何一項是 fail,session 才會是 completed。回報 skipped 的項目不影響 completed。要做 boolean 分支判斷「憑證有沒有通過」,看 status === "completed" 即可。要對使用者解釋失敗原因,巡 check_results 找 status: "fail" 的項,把 message 拿出來顯示。

回應(200 OK,failed — 逐項結果):

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "failed",
"created_at": "2026-04-01T00:00:00.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"verified_at": "2026-04-01T00:01:23.000Z",
"verification_mode": "fail_fast",
"check_results": [
{ "check": "credential_format", "status": "success", "reason_code": "credential_format_valid", "message": "The credential format is valid." },
{ "check": "signature", "status": "fail", "reason_code": "issuer_signature_invalid", "message": "The credential content does not match the issuer signature; authenticity could not be confirmed." },
{ "check": "key_binding", "status": "skipped", "reason_code": "prerequisite_failed", "message": "The signature check did not pass, so key binding was not evaluated." },
{ "check": "oid4vp_compliance", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "credential_status", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "issuer_trust", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "issuer_governance", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "schema_governance", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." },
{ "check": "schema_version", "status": "skipped", "reason_code": "skipped", "message": "A preceding check did not pass; this check was skipped." }
]
}

fail_fast 模式下,第一個失敗之後不再執行任何檢查:其餘每一項仍會出現在 check_results,標為 status: "skipped"、reason_code: "skipped"。run_all 模式即使遇到 fail 也跑完所有適用檢查 — 適合需要完整診斷給客服的場景。

模式設定的位置。 verification_mode 不是 POST /v1/verifier/authorization-request 的參數。它由錢包在送出 VP 到 POST /v1/verifier/presentation 時傳入:"run_all" 或 "fail_fast"(預設 "fail_fast")。這支請求的格式見非保管模式 § 第六步。保管模式的 Holder Service 不會傳 verification_mode,所以保管模式的 session 一律用 fail_fast。Verifier-side 只是把模式讀回來,並非在 request 建立時選擇模式。

驗證 pipeline 目前對外呈現的 check 名稱與 reason_code 封閉集合。可作為 triage 失敗或對應使用者文案的依據。

checkreason_code(成功)reason_code(失敗)含義
oid4vp_complianceoid4vp_request_validoid4vp_non_compliant、presentation_invalid、dcql_not_satisfiedOID4VP 請求 / 回應結構符合規範。dcql_not_satisfied 表示出示的憑證不滿足 dcql_query
credential_formatcredential_format_validcredential_format_invalid出示之 payload 可解析為 dc+sd-jwt
signaturesignature_verifiedissuer_signature_invalid、issuer_chain_untrusted、issuer_chain_expired、issuer_san_mismatch、issuer_key_not_resolvable、credential_expired、signature_verification_failed發行方簽章對解析出之公鑰驗證通過。只涵蓋發行方真實性 — 持有者的持有證明另以 key_binding 呈現。發行方以 x5c 憑證鏈簽章時,三個鏈相關碼直接指出該修哪裡:issuer_chain_untrusted 是信任錨設定、issuer_chain_expired 是憑證輪替、issuer_san_mismatch 表示憑證的 iss 無法綁定到葉憑證的 dNSName SAN — host 不在清單內、根本沒有 host,或該 SAN 清單無法用於綁定(萬用字元,或非 dNSName 項目)。issuer_key_not_resolvable 則收斂為「取不到金鑰」本身 — DID 無法解析,或憑證鏈根本無法解析成一條鏈
key_bindingkey_binding_verifiedkb_jwt_missing、kb_jwt_malformed、kb_jwt_typ_invalid、kb_jwt_signature_invalid、kb_jwt_nonce_mismatch、kb_jwt_aud_mismatch、kb_jwt_iat_missing、kb_jwt_iat_in_future、kb_jwt_iat_too_old、kb_jwt_sd_hash_mismatch、holder_key_not_resolvable持有者的 Key Binding JWT 證明其持有憑證 confirmation key 的私鑰,並將此次出示綁定到本次請求的 nonce、本 verifier 的 client_id,以及實際出示的 disclosures。與 signature 由同一個檢查一併回報。只要 signature 檢查未通過就另有 skipped / prerequisite_failed,代表 key binding 根本沒被評估 — 切勿讀成通過
credential_statuscredential_not_revokedcredential_revoked、credential_suspended、credential_status_unknown、status_list_unreachable、status_list_invalid憑證的 Token Status List 條目未標記為已撤銷或已暫停。另有 skipped 三種情形:status_check_disabled(此部署未啟用強制檢查)、status_not_applicable(憑證未帶 status 參照)、prerequisite_failed(沒有憑證進到這個檢查)
issuer_trust——發行方 DID 是否屬於 Trust Registry 中的租戶。一律回報 skipped,reason_code 為 issuer_in_tr_approved、issuer_in_tr_not_approved、issuer_not_in_tr、issuer_not_did(發行方是 URL 而非 DID),或 prerequisite_failed(無法判定發行方 DID)
issuer_governance——發行方的租戶是否已核准。一律回報 skipped,reason_code 為 partial_governance_coverage(已核准)或 prerequisite_failed(issuer_trust 沒有找到已核准的發行方)
issuer_governance_vct_scope——發行方是否註冊了出示的憑證類型(vct)。一律回報 skipped,reason_code 為 issuer_schema_scope_authorized 或 issuer_schema_scope_not_registered。只在 issuer_governance 回報 partial_governance_coverage 且憑證帶 vct 時出現
schema_governance——一律回報 skipped,reason_code 為 not_implemented
schema_version——一律回報 skipped,reason_code 為 not_implemented
(任一檢查)——status: "skipped" 搭配 reason_code: "skipped":fail_fast 模式下,因前面的檢查失敗而未執行

issuer_trust、issuer_governance、issuer_governance_vct_scope、schema_governance、schema_version 這幾項只記錄觀察結果:它們從不回報 success 或 fail,所以不會改變 session 的 status。觀察到什麼請看 reason_code —— skipped 並不代表底層性質已被驗證。

走 X.509 / x5c 路徑發行的憑證會依 draft-ietf-oauth-status-list-21 帶一個 status.status_list 參照 —— 一個清單 URI 加上一個索引。當該部署啟用撤銷狀態強制檢查時,Verifier Service 會在每次驗證時抓取該清單並讀取對應條目:

條目結果
有效credential_status 回報 success / credential_not_revoked
已撤銷400 invalid_vp_token、credential_revoked
已暫停400 invalid_vp_token、credential_suspended
保留值(0x03)400 invalid_vp_token、credential_status_unknown —— 無已註冊語意,因此不視為有效

未帶 status 參照的憑證 —— 包含所有 did:iota 發行的憑證 —— 會回報 skipped / status_not_applicable,驗證行為與過去完全相同。skipped 絕不代表憑證通過了撤銷檢查,只代表沒有可套用的檢查。

此檢查採 fail-closed。若清單無法取得或驗證不通過,驗證會被拒絕(status_list_unreachable、status_list_invalid),而不是放行 —— 「拿不到清單」絕不能被讀成「未被撤銷」。Status Issuer 短暫中斷時會以最後一次成功取得的 token 緩衝,但僅限於該 token 所宣告的 ttl 之內。

TCS 抓 Status List 時不跟隨轉址。回 3xx(例如從 http 轉到 https)會算成 status_list_invalid,所以 Status Issuer 必須在憑證裡寫的那個 URI 直接提供清單。

回應(200 OK,expired):

{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "expired",
"created_at": "2026-04-01T00:00:00.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"error": {
"code": "session_expired",
"message": "Session has expired"
}
}
Status意義
pendingRequest 已建立,等錢包來抓 request object
in_progress錢包已抓 request object,使用者尚未提交
completedVP token 驗證通過;presentation_metadata 已填,且 check_results 沒有任何一項是 fail(可以有 skipped)
failedcheck_results 至少一項是 fail(簽章錯、nonce 不對、憑證過期等),或提交在檢查開始前就被拒絕 — 此時 check_results 是空的
expiredSession 在錢包回應前 TTL 到期;error 已填

實務 poll loop(每 2 秒):

Terminal window
while true; do
RESULT=$(curl -s "$URL/v1/verifier/result/$SESSION_ID" -H "X-API-Key: $KEY")
STATUS=$(echo "$RESULT" | jq -r '.status')
case "$STATUS" in completed|failed|expired) echo "$RESULT" | jq .; break;; esac
sleep 2
done

push 模式 webhook(讓 verifier 後端不必 polling)為路線圖項目;在它推出之前,polling result 端點為唯一支援的整合路徑。如果 push 對你的部署是硬性需求,請聯繫我們。

狀態原因
401X-API-Key 缺或無效
404Session not found — 沒有這個 ID 的 session,或該 session 是用其他帳號的 API key 建立的

Verifier Service 有兩支唯讀端點,可查看你租戶的驗證 session — 例如用來做稽核畫面。兩支都用 X-API-Key,只回傳該 key 所屬租戶的 session。這些回應裡的 status 是大寫(PENDING、IN_PROGRESS、COMPLETED、FAILED、EXPIRED)。

Terminal window
curl "https://verifier.turingspace.co/v1/verifications?status=COMPLETED&status=FAILED&limit=20" \
-H "X-API-Key: tcs_production_<your-api-key>"
Query 參數型別說明
statusstring,可重複只回傳這些狀態的 session。
verified_afterISO 8601 日期只回傳 verified_at 在此時間(含)之後的 session。
verified_beforeISO 8601 日期只回傳 verified_at 在此時間之前的 session。必須晚於 verified_after,且兩者間隔不能超過 90 天。
qstring對 session_id 做部分比對,不分大小寫。
offsetinteger略過的筆數(預設 0)。
limitinteger回傳筆數,1 到 100(預設 20)。

沒有 verified_at 的 session 不會符合 verified_after 或 verified_before。

回應(200 OK) — 依 created_at 由新到舊排序:

{
"items": [
{
"session_id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"status": "COMPLETED",
"created_at": "2026-04-01T00:00:00.000Z",
"verified_at": "2026-04-01T00:01:23.000Z",
"expires_at": "2026-04-01T00:05:00.000Z",
"dcql_query_id": "identity_credential",
"verifier_client_id": "did:iota:0xae72f18dc7b6af5b740edae8e4e0b2d3c9fb10a4e7d6c5b3a2f1e0d9c8b7a6f5"
}
],
"total": 1,
"offset": 0,
"limit": 20
}

dcql_query_id 是 dcql_query.credentials 第一項的 id。

回傳單一 session 的完整內容。欄位:

欄位說明
session_id、status、created_at、verified_at、expires_at同列表。completed_at 與 verified_at 相同。
client_id該 request 的 verifier_client_id。
nonce、staterequest object 中送給錢包的值。
dcql_query_id、dcql_query該 request 的 query。
holder_did通過驗證之出示的 holder DID。Session 不是 COMPLETED 時為 null。
disclosed_credentials每張提交的憑證一筆:query_id、vct、issuer_did、holder_did、issued_at、expires_at、disclosures({ "name", "value" };無法解碼的段落為 { "raw", "parse_error": true })與 jwt_claims。Session 不是 COMPLETED 時為 null。
check_results與 result 端點相同的項目,或 null。
errorcheck_results 中第一個 status: "fail" 項目的 message,或 null。
vp_tokenTCS 儲存的已通過出示:一個 JSON 字串,內容是以 DCQL credential id 為 key、值為含其 SD-JWT 之陣列的物件({"<id>": ["<sd-jwt>"]})。這不是原始 request body;direct_post.jwt 時是解密後的內容。Session 不是 COMPLETED 時為 null。
狀態原因
400Query 參數無效(未知的 status、日期不是 ISO 8601、verified_before 沒有晚於 verified_after、間隔超過 90 天、limit 不在 1–100)
401X-API-Key 缺或無效
404Session not found — 你的租戶沒有這個 ID 的 session(僅單筆端點)

DCQL(Digital Credentials Query Language)描述你向 holder 要哪些憑證、哪些 claim。每個 authorization request 都需要 dcql_query。

{
"dcql_query": {
"credentials": [ /* 一個或多個 credential descriptor */ ],
"credential_sets": [ /* 選填 */ ]
}
}

credential_sets(選填)會放進 request object 送給錢包。每一項有 options(非空的陣列,每個元素是一組憑證 id 的陣列,代表一種可接受的組合)、required(預設 true)與 purpose(錢包可顯示的請求原因)。Verifier 仍要求 credentials 的每一項都有符合的憑證:credential_sets 不會讓任何憑證變成選填。

欄位型別必填說明
idstring是該 credential 在這份 query 內的識別符 — Holder Service 在 selected_credentials[].query_id 也會引用。
formatstring是SD-JWT VC 用 "dc+sd-jwt"。也接受 "vc+sd-jwt"。
metaobject是放憑證格式相關的限制條件。即使只設定其中一個內部欄位也是必填。
meta.vct_valuesstring[]否可接受的 VCT URL。錢包對照憑證上的 vct claim。
meta.type_valuesstring[][]否可接受的憑證 type 組合。憑證的 type 必須包含至少一個內層陣列的所有值,否則回 dcql_not_satisfied。
claimsobject[]否要的 claim,每個用 { "path": [...] }。省略則由錢包決定。
multipleboolean否預設 false。為 false 時,同一個 id 提交超過一張憑證會以 dcql_not_satisfied 失敗。
require_cryptographic_holder_bindingboolean否預設 true。要求錢包提供 holder binding 證明。
trusted_authoritiesobject[]否限定特定 issuer,例如 [{ "type": "did", "values": ["did:iota:0x..."] }]。

每個 claim path 是從憑證根開始的 JSON path:["credentialName"]、["degreeName"]。沒列的東西在 SD-JWT selective disclosure 下保持隱藏。

範例 — 大學學位 + 鎖定信任 issuer

Section titled “範例 — 大學學位 + 鎖定信任 issuer”
{
"dcql_query": {
"credentials": [
{
"id": "degree_credential",
"format": "dc+sd-jwt",
"meta": {
"vct_values": ["https://schema-registry.turingspace.co/schemas/UniversityDegreeCredential/v1"]
},
"claims": [
{ "path": ["credentialName"] },
{ "path": ["studentId"] },
{ "path": ["degreeName"] }
],
"trusted_authorities": [
{ "type": "did", "values": ["did:iota:0xabc123def456"] }
]
}
]
}
}

Holder 會在同意畫面看到這三個 claim;其他全部隱藏。


  • 把 verifier_private_key 當設定。 它是簽章金鑰 — 放 secret manager、需要時才取,不要進跟原始碼一起 commit 的 .env。
  • 無限 poll。 一定要尊重 Step 1 回的 expires_at。Session 過期(status: expired)就停止 poll、回報失敗給 user。
  • 要太多 claim。 錢包同意畫面會列出所有 claim path — 要 10 個 optional 欄位會訓練 user 不讀就同意。要最小集合。
  • 忘記 vct_values。 沒這欄錢包可能配出無關類型的憑證。
  • verifier_client_id 用一般 URL。 Verifier Service 只接受註冊在你帳號下的 DID,或 x509_san_dns: / x509_hash: client ID。其他值都會被當成 DID 處理,並以 400 失敗。