Issuer · 發行憑證
這頁是給 Issuer 角色:簽出並交付憑證的組織。從你的後端視角,發行其實只是一支 API 呼叫 — POST /v1/offers。其後(fetch offer、換 code、組 proof JWT、取 SD-JWT)都在錢包端完成;保管模式下由 TCS Holder Service 替你做。
你做什麼 vs. TCS 做什麼
Section titled “你做什麼 vs. TCS 做什麼”你要實作的兩步:
- 建立 offer。 你的後端把 credential payload POST 到 Credential Issuer。TCS 回 offer URI 與 deep link。
- 交付 offer。
- 保管模式: 把
credential_offer_uri直接傳給 Holder Service 的POST /v1/oid4vci/receive。 - 非保管模式: 把
deep_link渲染成 QR code,或以推播 / email 送給 end user 的錢包 App。
- 保管模式: 把
兩種模式下你都不需要自己跑 OID4VCI 的 token / nonce / proof / credential 那套 — 保管模式由 Holder Service 做,非保管模式由 user 錢包做(wire-level 細節見非保管模式)。
Step 1 · 建立 credential offer
Section titled “Step 1 · 建立 credential offer”用你的 Issuer API key 對 Credential Issuer 打。Offer 帶著憑證型別、claims、與 flow 設定。
curl -X POST https://issuer.turingspace.co/v1/offers \ -H "Content-Type: application/json" \ -H "X-API-Key: tcs_production_<your-api-key>" \ -d '{ "credential": { "config_id": "TuringCerts_Standard_Credential_v2_sd_jwt", "claims": { "credentialName": "University Degree", "issuedTime": "2026-03-26T00:00:00Z" } }, "flow": "pre-authorized", "expires_in": 3600 }'回應(201 Created):
{ "offer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "credential_offer_uri": "https://issuer.turingspace.co/v1/offers/a1b2c3d4-e5f6-7890-abcd-ef1234567890", "deep_link": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fissuer.turingspace.co%2Fv1%2Foffers%2Fa1b2c3d4-e5f6-7890-abcd-ef1234567890", "expires_at": "2026-03-26T01:00:00Z"}| 名稱 | 型別 | 必填 | 說明 |
|---|---|---|---|
credential.config_id | string | 是 | Issuer metadata credential_configurations_supported map 的 key。可用 GET /.well-known/openid-credential-issuer/:tenant 查詢可用 ID。 |
credential.claims | object | 是 | 要包含的憑證 claims(鍵值對)。會依憑證型別的 JSON Schema 驗證;不符合的 claims 會以 400 拒絕。 |
flow | string | 是 | 發行流程型別。請使用 "pre-authorized"。API 也接受 "authorization-code",但用這個流程目前無法完成發卡,請不要使用。 |
expires_in | number | 否 | Offer 存活秒數(預設 3600)。最小 60、最大 86400。flow: "pre-authorized" 時最大為 3600,超過會回 400。 |
require_transaction_code | boolean | 否 | 預設 false。不支援 transaction code(PIN):設 true 會回 400。 |
issuer_did | string | 否 | 為這張 offer 覆寫預設 issuer DID。必須與 issuer_private_key 一起提供 —— 缺一補一會回 400。 |
holder_did | string | 否 | 把 offer 綁定到特定 holder DID。 |
issuer_private_key | string | 否 | 覆寫預設 issuer 簽章金鑰。必須與 issuer_did 一起提供 —— 缺一補一會回 400。 |
notarize_on_iota | boolean | 否 | 是否把這張憑證錨點到 IOTA。issuer_did 為 did:iota:* 時預設 true,其餘 false。明確設 true 時 issuer_did 必須是 did:iota:*。見 鏈上 notarization。 |
callback_url | string | 否 | 鏈上 notarization 完成後 TCS 會 POST 的 HTTP 或 HTTPS URL(必須帶 scheme)。單次交付、不重試。只會呼叫公開位址:host 是(或解析到)private、loopback 等非公開位址的 URL 永遠不會被呼叫,也不會回錯誤。notarize_on_iota=false 時仍會儲存但永不觸發。最長 2048 字元。見 Step 3 · 追蹤發行狀態。 |
| 狀態 | 原因 |
|---|---|
| 400 | Body 驗證失敗(缺欄位、claims 格式錯、config_id 不存在,或 claims 不符合憑證型別的 JSON Schema);亦於 issuer_did 與 issuer_private_key 未同時提供 / 同時省略、expires_in 超出範圍,或 require_transaction_code 為 true 時回傳 |
| 400 | issuer_did 未註冊,或此部署的 IOTA 連線已停用(帶 issuer_did 的 offer 需要 IOTA 連線) |
| 401 | 缺 X-API-Key 或 key 無效 |
| 403 | 所提供的 issuer_did 註冊在其他帳號名下 |
Step 2 · 交付 offer
Section titled “Step 2 · 交付 offer”credential_offer_uri 怎麼交付,看你的模式。
直接把 URI 交給 Holder Service。後端已經握有該 user 的 access token 與 DID 私鑰(見 Holder · 管理錢包與憑證 § 1)。
curl -X POST https://holder.turingspace.co/v1/oid4vci/receive \ -H "Authorization: Bearer ${HOLDER_USER_ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "credential_offer_uri": "openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fissuer.turingspace.co%2Fv1%2Foffers%2Fa1b2c3d4-...", "holder_did": "did:iota:testnet:0x7a8b...", "private_key": "${HOLDER_PRIVATE_KEY}" }'一次 round trip 就把憑證放進 Holder Service 該 user 的錢包。完整流程見 Holder · 管理錢包與憑證 § 2。
把 deep_link 渲染成 QR code、email、或推播。剩下的 OID4VCI 由 user 的錢包 App 直接跟 TCS 跑(見非保管模式)。
Step 3 · 追蹤發行狀態
Section titled “Step 3 · 追蹤發行狀態”Offer 交付之後,有兩種方式可以得知憑證實際發出並完成鏈上錨點:一是 TCS 在鏈上 notarization 完成後主動 POST 的 webhook,二是隨時可查的 polling 端點。
實務上把 webhook 當主訊號、polling 當 fallback。Webhook 為單次交付 —— production 程式碼應在 webhook 未於可接受時間內抵達時,改用 polling 補上。
Webhook(推送)
Section titled “Webhook(推送)”在 POST /v1/offers 帶 callback_url。當該張憑證的鏈上錨點建立完成,TCS 會對該 URL POST 一份 JSON。
Payload:
{ "event": "credential.notarized", "offer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "credential_id": "8f7d2c3a-9b1e-4f3a-b7c6-1a2b3c4d5e6f", "object_id": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b", "blockchain": "iota", "notarized_at": "2026-05-12T08:30:00.000Z"}交付語意:
- HTTP
POST、Content-Type: application/json。 - 單次交付、不重試。Receiver 應回
2xx;非2xx會被 TCS 記下,但不會再送。 - Timeout 預設 5 秒。
- 不 follow redirects。
- 只送到公開位址。
callback_url的 host 是(或解析到)private、loopback 等非公開位址時,TCS 不會送出 webhook。POST /v1/offers仍會接受這個 URL,所以接收端請用公開可連線的位址。 - 只在憑證實際完成鏈上錨點時觸發 —— 即
notarize_on_iota=true且 issuer 走did:iota路徑。X.509 issuer 與notarize_on_iota=false的 offer 不會觸發(見 鏈上 notarization)。
Polling(拉取)
Section titled “Polling(拉取)”GET /v1/offers/{offerId}/credentials 回該 offer 已發出的憑證。在 webhook 不可用(X.509 路徑、notarize_on_iota=false)、或 webhook 未到、或想隨時做一次同步狀態查詢時使用。
curl https://issuer.turingspace.co/v1/offers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/credentials \ -H "X-API-Key: tcs_production_<your-api-key>"回應(200 OK)—— offer 尚未被兌換:
[]回應(200 OK)—— on_chain_status: PENDING(排隊中):
[ { "credential_id": "8f7d2c3a-9b1e-4f3a-b7c6-1a2b3c4d5e6f", "issuer_did": "did:iota:issuer-ntu-001", "holder_did": "did:iota:holder-xyz", "vct": "https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2", "format": "dc+sd-jwt", "status": "ACTIVE", "blockchain": "IOTA", "on_chain_status": "PENDING", "object_id": null, "issued_at": "2026-05-12T08:30:00.000Z", "expires_at": null, "revoked_at": null }]回應(200 OK)—— on_chain_status: IN_PROGRESS:
[ { "...same shape as above...", "on_chain_status": "IN_PROGRESS", "object_id": null }]回應(200 OK)—— on_chain_status: COMPLETED(發行完成):
[ { "...same shape as above...", "on_chain_status": "COMPLETED", "object_id": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b" }]回應(200 OK)—— on_chain_status: FAILED(永久失敗):
[ { "...same shape as above...", "on_chain_status": "FAILED", "object_id": null }]| 欄位 | 值 | 意義 |
|---|---|---|
status | ACTIVE / SUSPENDED / REVOKED / EXPIRED / DELETED | 憑證 lifecycle |
on_chain_status | PENDING / IN_PROGRESS / COMPLETED / FAILED / null | Notarization 進度。終局狀態為 COMPLETED 與 FAILED。憑證未上鏈時為 null。 |
object_id | string / null | IOTA object id;僅在 on_chain_status 為 COMPLETED 時有值 |
blockchain | IOTA / null | 錨點網路(此處為大寫;webhook payload 用小寫 iota)。憑證未上鏈時為 null。 |
| 狀態 | 原因 |
|---|---|
| 400 | offerId 不是合法 UUID |
| 401 | 缺 X-API-Key 或 key 無效 |
| 404 | Offer 不存在,或不屬於這支 API key(兩種情況故意無法區分) |
管理已發出的憑證
Section titled “管理已發出的憑證”Credential Issuer 的這組端點可以列出、查詢、撤銷、暫停與恢復你的 tenant 發出的憑證。全部都用 X-API-Key 帶 Issuer API key,且只看得到自己 tenant 的憑證:憑證不存在與憑證屬於其他 tenant 都回 404。這裡的 credential_id 與 polling 端點、webhook 回的是同一個值。
| Method | Path | 用途 |
|---|---|---|
GET | /v1/credentials | 列出已發出的憑證(分頁) |
GET | /v1/credentials/{credential_id} | 查詢單張憑證 |
PATCH | /v1/credentials/{credential_id}/revoke | 撤銷(永久) |
PATCH | /v1/credentials/{credential_id}/suspend | 暫停(可恢復) |
PATCH | /v1/credentials/{credential_id}/reinstate | 把暫停中的憑證恢復為 ACTIVE |
curl "https://issuer.turingspace.co/v1/credentials?status=ACTIVE&limit=20" \ -H "X-API-Key: tcs_production_<your-api-key>"結果依 issued_at 由新到舊排序。
| Query param | 型別 | 說明 |
|---|---|---|
status | string | 依狀態篩選:ACTIVE、REVOKED、EXPIRED、DELETED 或 SUSPENDED。要比對多個狀態就重複帶這個參數。 |
config_id | string | 完全比對 credential configuration ID |
vct | string | 完全比對 VCT |
issued_after | string | ISO 8601 日期。發出時間在此時間(含)之後的憑證。 |
issued_before | string | ISO 8601 日期。發出時間嚴格早於此時間的憑證。必須晚於 issued_after,且兩者間隔不得超過 90 天。 |
q | string | 對 credential_id 或 holder_did 做不分大小寫的子字串搜尋 |
offset | integer | 略過的筆數。預設 0,最小 0。 |
limit | integer | 回傳筆數。預設 20,範圍 1–100。 |
回應(200 OK):
{ "items": [ { "credential_id": "8f7d2c3a-9b1e-4f3a-b7c6-1a2b3c4d5e6f", "config_id": "TuringCerts_Standard_Credential_v2_sd_jwt", "vct": "https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2", "status": "ACTIVE", "issued_at": "2026-05-12T08:30:00.000Z", "expires_at": null, "revoked_at": null, "holder_did": "did:iota:holder-xyz", "format": "dc+sd-jwt", "signing_method": "es256-x509" } ], "total": 1, "offset": 0, "limit": 20}signing_method 為 eddsa-did、es256-x509 或 null。
查詢單張憑證
Section titled “查詢單張憑證”GET /v1/credentials/{credential_id} 回傳一筆,欄位與列表項目相同,另外多出:
| 欄位 | 型別 | 說明 |
|---|---|---|
issuer_did | string / null | Issuer DID |
notarized_at | string / null | 憑證完成鏈上錨點的時間(ISO 8601) |
on_chain_status | string / null | 值與 Polling 段相同 |
object_id | string / null | 鏈上 object id |
blockchain | string / null | 錨點網路(IOTA) |
raw_claims | object | SD-JWT 解碼後的 JWT payload。_sd 項目是 disclosure 的 hash,不是 claim 值。憑證無法解析時為空物件。 |
撤銷、暫停、恢復
Section titled “撤銷、暫停、恢復”curl -X PATCH https://issuer.turingspace.co/v1/credentials/8f7d2c3a-9b1e-4f3a-b7c6-1a2b3c4d5e6f/revoke \ -H "X-API-Key: tcs_production_<your-api-key>"不需要 request body。每個動作都回 200 OK,內容是該憑證,格式與查詢單張憑證相同。呼叫回傳時,已發布的 Status List Token 就已經更新。
| 動作 | 允許的起始狀態 | 結果 |
|---|---|---|
revoke | ACTIVE、SUSPENDED | REVOKED,並寫入 revoked_at。永久生效:撤銷後不能再暫停或恢復。 |
suspend | ACTIVE | SUSPENDED。revoked_at 維持空值。 |
reinstate | SUSPENDED | ACTIVE |
憑證有 status list 項目時,若它已經是目標狀態,再呼叫同一動作會回 200 與目前狀態,不做任何變更。
| 狀態 | 原因 |
|---|---|
| 400 | 僅列表:query 參數不合法(status 不在清單內、日期格式錯、issued_before 未晚於 issued_after、間隔超過 90 天、limit 或 offset 超出範圍) |
| 401 | 缺 X-API-Key 或 key 無效 |
| 404 | 憑證不存在,或屬於其他 tenant(兩種情況故意無法區分) |
| 409 | 僅動作端點。憑證沒有 status list 項目、任何 verifier 都觀察不到狀態變更時,message 以 credential_not_revocable 開頭;目前狀態不允許該動作時(例如暫停或恢復一張 REVOKED 憑證),message 以 invalid_status_transition 開頭。 |
鏈上 notarization
Section titled “鏈上 notarization”TCS 在簽出 SD-JWT VC 之外,可以把每張憑證同步發布到 IOTA Tangle。鏈上 object 儲存 issuer 簽過的 JWT,任何人拿到 object_id 就有一份長期、可由第三方獨立驗證的紀錄 —— 不依賴 TCS 或 issuer 的線上可用性。多數 TCS 客戶採用此模式,也是平台預設。
何時選擇上鏈
Section titled “何時選擇上鏈”- 公部門或合規場景,需要憑證在簽發後多年仍可稽核。
- 跨組織憑證,需要在不呼叫 TCS 的情況下被獨立驗證。
- 任何把「簽發事件本身」視為公開可解析資產的流程。
若以上皆非適用情境(例如純內部員工識別、無外部 relying party),則設 notarize_on_iota: false 略過鏈上錨點,僅使用離線 SD-JWT。
決定點只在 offer 建立時 —— POST /v1/offers 的 notarize_on_iota 欄位(見 Step 1 參數)。同一張 offer 會把這個旗標帶到後續任一交付模式(保管 / 非保管);credential 請求本身沒有單張覆寫機制,錢包 credential 請求中夾帶的 is_on_chain 會被忽略。
| Issuer 簽章路徑 | notarize_on_iota 預設 | 呼叫方可設定 |
|---|---|---|
did:iota:* | true | true(預設)或 false 略過上鏈 |
X.509 / x5c | false | 僅可設 false(預設)—— 明確設 true 會在 offer 建立時回 400 |
Offer 一旦建立,credential 請求無法再改變結果。
路徑限制 —— 只走 DID 路徑
Section titled “路徑限制 —— 只走 DID 路徑”鏈上 notarization 僅在 issuer 走 did:iota(EdDSA)簽章路徑、且 issuer_private_key 可提供給 TCS 時才會執行。註冊於 X.509 / x5c 路徑(HAIP 合規)的 issuer 無法上鏈 —— 當 issuer_did 非 did:iota:* 時,offer 建立階段設 notarize_on_iota: true 會被 400 拒絕。需要鏈上錨點的客戶必須註冊 did:iota issuer;HAIP 與上鏈目前無法同時並存。路徑比較見 DID · 兩條發行方簽章路徑。
Notarization 在憑證發出之後才執行,所以 holder-receive 回應不帶鏈上錨點。回應是一筆扁平的憑證紀錄:
{ "credential_id": "550e8400-e29b-41d4-a716-446655440000", "vct": "https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2", "schema_id": "TuringCerts_Standard_Credential_v2_sd_jwt", "issuer_did": "did:iota:testnet:0x1234...", "holder_did": "did:iota:testnet:0x7a8b...", "raw_credential": "eyJhbGciOiJFZERTQSIs...~<disclosure>~...", "issued_at": "2026-05-12T08:30:00.000Z", "expires_at": "2027-05-12T08:30:00.000Z", "status": "ACTIVE"}schema_id 已棄用,值與 vct 相同;憑證沒有到期時間時不帶 expires_at。錨點的 object_id 請從 credential.notarized webhook 取得,或在 on_chain_status 為 COMPLETED 後從 GET /v1/offers/{offerId}/credentials 取得。離線(notarize_on_iota: false)的憑證不會有 object_id。
如何驗證鏈上紀錄
Section titled “如何驗證鏈上紀錄”鏈上 object 儲存的是 issuer 簽過的 JWT(header.payload.signature —— SD-JWT VC 的簽章部分,未附加 disclosures)。要在不依賴 TCS 的情況下驗證:
- 從 webhook payload 或
GET /v1/offers/{offerId}/credentials取得憑證的object_id。 - 在對應網路(testnet / mainnet)的 IOTA Notarization explorer 上解析該 object ——
state欄位就是 JWT bytes。 - 解析 issuer DID(
did:iota:...),對 DID Document 上的驗證方法驗章。
成功解析 + 驗章即為獨立證明:issuer 在鏈上 object 建立的時間點確實簽出了該張憑證。
移除鏈上紀錄
Section titled “移除鏈上紀錄”鏈上 object 原則上可解(unpublish notarization 交易),但目前未公開 API。若需移除特定 object_id(例如隱私 / 個資刪除請求),請聯絡 TCS 團隊並提供 credential_id 與 object_id。同步參見 架構 · 合規與資料處理 · 當事人刪除權。
進階 · Pre-authorized code flow
Section titled “進階 · Pre-authorized code flow”本頁的 offer 都使用預授權碼流程 — Issuer 在離線端認證 holder(例如在你產品內),然後把一次性的 pre-auth code 嵌進 offer。這是最簡單、也是保管模式採用的方式。
- Holder · 管理錢包與憑證 — 保管模式下後端拿 offer URI 之後做什麼。
- Verifier · 驗證憑證 — 生命週期的另一半。
- 非保管模式 — Holder 是外部錢包時的差異。
- 身份驗證 — DPoP、API key、JWT 細節。