Verifier · 驗證憑證
這頁是給 Verifier 角色:要求 holder 證明某件事的服務。從你的後端視角,驗證只有兩支 API 呼叫 — 建立 authorization request、然後讀結果。中間的事(取得簽妥的 request object、提示 user、組 VP token、提交)都在錢包端。
你做什麼 vs. TCS 做什麼
Section titled “你做什麼 vs. TCS 做什麼”你要實作的:
- 建立 request。 POST 你的 DCQL query 與 verifier 身分到 Verifier Service。
- 交付 request URI。
- 保管模式: 代表 user 呼叫 Holder Service
POST /v1/oid4vp/presentation。 - 非保管模式: 把 deep link 渲染成 QR 給 user 的錢包 App。
- 保管模式: 代表 user 呼叫 Holder Service
- Poll 結果。 監看
GET /v1/verifier/result/{session_id}直到 session 變completed。
VP token、SD-JWT 簽章、key-binding JWT 你都不用自己組或驗。Verifier Service 全做完,結果端點上會回 status(整體通過/失敗)與 check_results[](逐項檢查)。
Step 1 · 建立 authorization request
Section titled “Step 1 · 建立 authorization request”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_query | object | 是 | 你要哪些憑證、哪些 claim。詳見 DCQL Query Structure。 |
verifier_private_key | string | 僅 DID | Base64url 編碼的原生 Ed25519(32 bytes)。用來簽 JAR(request object)讓錢包驗「是誰在問」。verifier_client_id 是 DID 時必填;x509_san_dns: 與 x509_hash: client ID 不要帶。 |
verifier_client_id | string | 是 | 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_mode | string | 否 | "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_in | number | 否 | Session TTL 秒數,60 到 3600(預設 300)。 |
client_metadata | object | 否 | client_name、logo_uri、policy_uri、tos_uri — 顯示在錢包同意畫面。vp_formats_supported — 你接受的憑證格式與演算法;省略時 TCS 送出 dc+sd-jwt 搭配 ES256 與 EdDSA。jwks — 回應加密用的公鑰;用 direct_post.jwt 時 TCS 會以 ephemeral 公鑰取代。 |
redirect_uri | string | 否 | 錢包提交後把 user redirect 去哪。Headless 流程可省略。 |
request_uri_method | string | 否 | "get"(預設)或 "post"。設為 "post" 時,authorization_request 會帶 request_uri_method=post,錢包改用 HTTP POST 取 request object。 |
| 狀態 | 原因 |
|---|---|
| 400 | Body 格式錯(缺欄位、dcql_query.credentials 為空、expires_in 不在 60–3600 等);DID client ID 沒帶 verifier_private_key、未註冊在你帳號下,或金鑰對不上;x509_ client ID 不在 server X.509 材料涵蓋範圍內 |
| 401 | X-API-Key 缺或無效 |
Step 2 · 交付 request URI
Section titled “Step 2 · 交付 request URI”把 request 送到 holder 面前的方式取決於模式。
代表 user 把 authorization_request 傳給 Holder Service。Holder Service 會 fetch 簽妥的 request、提示 user、組 VP token、提交。詳見 Holder · 管理錢包與憑證 § 4。
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 — 這支請求的格式見非保管模式 § 第六步。
Step 3 · 檢查驗證結果
Section titled “Step 3 · 檢查驗證結果”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 建立時選擇模式。
reason_code 對照
Section titled “reason_code 對照”驗證 pipeline 目前對外呈現的 check 名稱與 reason_code 封閉集合。可作為 triage 失敗或對應使用者文案的依據。
check | reason_code(成功) | reason_code(失敗) | 含義 |
|---|---|---|---|
oid4vp_compliance | oid4vp_request_valid | oid4vp_non_compliant、presentation_invalid、dcql_not_satisfied | OID4VP 請求 / 回應結構符合規範。dcql_not_satisfied 表示出示的憑證不滿足 dcql_query |
credential_format | credential_format_valid | credential_format_invalid | 出示之 payload 可解析為 dc+sd-jwt |
signature | signature_verified | issuer_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_binding | key_binding_verified | kb_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_status | credential_not_revoked | credential_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 值
Section titled “Status 值”| Status | 意義 |
|---|---|
pending | Request 已建立,等錢包來抓 request object |
in_progress | 錢包已抓 request object,使用者尚未提交 |
completed | VP token 驗證通過;presentation_metadata 已填,且 check_results 沒有任何一項是 fail(可以有 skipped) |
failed | check_results 至少一項是 fail(簽章錯、nonce 不對、憑證過期等),或提交在檢查開始前就被拒絕 — 此時 check_results 是空的 |
expired | Session 在錢包回應前 TTL 到期;error 已填 |
實務 poll loop(每 2 秒):
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 2donepush 模式 webhook(讓 verifier 後端不必 polling)為路線圖項目;在它推出之前,polling result 端點為唯一支援的整合路徑。如果 push 對你的部署是硬性需求,請聯繫我們。
| 狀態 | 原因 |
|---|---|
| 401 | X-API-Key 缺或無效 |
| 404 | Session not found — 沒有這個 ID 的 session,或該 session 是用其他帳號的 API key 建立的 |
列出與查看驗證紀錄
Section titled “列出與查看驗證紀錄”Verifier Service 有兩支唯讀端點,可查看你租戶的驗證 session — 例如用來做稽核畫面。兩支都用 X-API-Key,只回傳該 key 所屬租戶的 session。這些回應裡的 status 是大寫(PENDING、IN_PROGRESS、COMPLETED、FAILED、EXPIRED)。
GET /v1/verifications
Section titled “GET /v1/verifications”curl "https://verifier.turingspace.co/v1/verifications?status=COMPLETED&status=FAILED&limit=20" \ -H "X-API-Key: tcs_production_<your-api-key>"| Query 參數 | 型別 | 說明 |
|---|---|---|
status | string,可重複 | 只回傳這些狀態的 session。 |
verified_after | ISO 8601 日期 | 只回傳 verified_at 在此時間(含)之後的 session。 |
verified_before | ISO 8601 日期 | 只回傳 verified_at 在此時間之前的 session。必須晚於 verified_after,且兩者間隔不能超過 90 天。 |
q | string | 對 session_id 做部分比對,不分大小寫。 |
offset | integer | 略過的筆數(預設 0)。 |
limit | integer | 回傳筆數,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。
GET /v1/verifications/{session_id}
Section titled “GET /v1/verifications/{session_id}”回傳單一 session 的完整內容。欄位:
| 欄位 | 說明 |
|---|---|
session_id、status、created_at、verified_at、expires_at | 同列表。completed_at 與 verified_at 相同。 |
client_id | 該 request 的 verifier_client_id。 |
nonce、state | request 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。 |
error | check_results 中第一個 status: "fail" 項目的 message,或 null。 |
vp_token | TCS 儲存的已通過出示:一個 JSON 字串,內容是以 DCQL credential id 為 key、值為含其 SD-JWT 之陣列的物件({"<id>": ["<sd-jwt>"]})。這不是原始 request body;direct_post.jwt 時是解密後的內容。Session 不是 COMPLETED 時為 null。 |
| 狀態 | 原因 |
|---|---|
| 400 | Query 參數無效(未知的 status、日期不是 ISO 8601、verified_before 沒有晚於 verified_after、間隔超過 90 天、limit 不在 1–100) |
| 401 | X-API-Key 缺或無效 |
| 404 | Session not found — 你的租戶沒有這個 ID 的 session(僅單筆端點) |
DCQL Query Structure
Section titled “DCQL Query Structure”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 不會讓任何憑證變成選填。
Credential descriptor 欄位
Section titled “Credential descriptor 欄位”| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
id | string | 是 | 該 credential 在這份 query 內的識別符 — Holder Service 在 selected_credentials[].query_id 也會引用。 |
format | string | 是 | SD-JWT VC 用 "dc+sd-jwt"。也接受 "vc+sd-jwt"。 |
meta | object | 是 | 放憑證格式相關的限制條件。即使只設定其中一個內部欄位也是必填。 |
meta.vct_values | string[] | 否 | 可接受的 VCT URL。錢包對照憑證上的 vct claim。 |
meta.type_values | string[][] | 否 | 可接受的憑證 type 組合。憑證的 type 必須包含至少一個內層陣列的所有值,否則回 dcql_not_satisfied。 |
claims | object[] | 否 | 要的 claim,每個用 { "path": [...] }。省略則由錢包決定。 |
multiple | boolean | 否 | 預設 false。為 false 時,同一個 id 提交超過一張憑證會以 dcql_not_satisfied 失敗。 |
require_cryptographic_holder_binding | boolean | 否 | 預設 true。要求錢包提供 holder binding 證明。 |
trusted_authorities | object[] | 否 | 限定特定 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失敗。
- Holder · 管理錢包與憑證 — 保管模式下 Step 2 的 request URI 怎麼變成 presentation。
- Issuer · 發行憑證 — 生命週期的另一半。
- 信任與 Schema 治理 — 註冊 verifier、決定接受哪些憑證。
- 身份驗證 — API key、JWT、DPoP 細節。