跳到內容

Issuer · 發行憑證

這頁是給 Issuer 角色:簽出並交付憑證的組織。從你的後端視角,發行其實只是一支 API 呼叫 — POST /v1/offers。其後(fetch offer、換 code、組 proof JWT、取 SD-JWT)都在錢包端完成;保管模式下由 TCS Holder Service 替你做。


Rendering diagram...

你要實作的兩步:

  1. 建立 offer。 你的後端把 credential payload POST 到 Credential Issuer。TCS 回 offer URI 與 deep link。
  2. 交付 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 細節見非保管模式)。


用你的 Issuer API key 對 Credential Issuer 打。Offer 帶著憑證型別、claims、與 flow 設定。

Terminal window
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_idstring是Issuer metadata credential_configurations_supported map 的 key。可用 GET /.well-known/openid-credential-issuer/:tenant 查詢可用 ID。
credential.claimsobject是要包含的憑證 claims(鍵值對)。會依憑證型別的 JSON Schema 驗證;不符合的 claims 會以 400 拒絕。
flowstring是發行流程型別。請使用 "pre-authorized"。API 也接受 "authorization-code",但用這個流程目前無法完成發卡,請不要使用。
expires_innumber否Offer 存活秒數(預設 3600)。最小 60、最大 86400。flow: "pre-authorized" 時最大為 3600,超過會回 400。
require_transaction_codeboolean否預設 false。不支援 transaction code(PIN):設 true 會回 400。
issuer_didstring否為這張 offer 覆寫預設 issuer DID。必須與 issuer_private_key 一起提供 —— 缺一補一會回 400。
holder_didstring否把 offer 綁定到特定 holder DID。
issuer_private_keystring否覆寫預設 issuer 簽章金鑰。必須與 issuer_did 一起提供 —— 缺一補一會回 400。
notarize_on_iotaboolean否是否把這張憑證錨點到 IOTA。issuer_did 為 did:iota:* 時預設 true,其餘 false。明確設 true 時 issuer_did 必須是 did:iota:*。見 鏈上 notarization。
callback_urlstring否鏈上 notarization 完成後 TCS 會 POST 的 HTTP 或 HTTPS URL(必須帶 scheme)。單次交付、不重試。只會呼叫公開位址:host 是(或解析到)private、loopback 等非公開位址的 URL 永遠不會被呼叫,也不會回錯誤。notarize_on_iota=false 時仍會儲存但永不觸發。最長 2048 字元。見 Step 3 · 追蹤發行狀態。
狀態原因
400Body 驗證失敗(缺欄位、claims 格式錯、config_id 不存在,或 claims 不符合憑證型別的 JSON Schema);亦於 issuer_did 與 issuer_private_key 未同時提供 / 同時省略、expires_in 超出範圍,或 require_transaction_code 為 true 時回傳
400issuer_did 未註冊,或此部署的 IOTA 連線已停用(帶 issuer_did 的 offer 需要 IOTA 連線)
401缺 X-API-Key 或 key 無效
403所提供的 issuer_did 註冊在其他帳號名下

credential_offer_uri 怎麼交付,看你的模式。

直接把 URI 交給 Holder Service。後端已經握有該 user 的 access token 與 DID 私鑰(見 Holder · 管理錢包與憑證 § 1)。

Terminal window
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 跑(見非保管模式)。


Offer 交付之後,有兩種方式可以得知憑證實際發出並完成鏈上錨點:一是 TCS 在鏈上 notarization 完成後主動 POST 的 webhook,二是隨時可查的 polling 端點。

實務上把 webhook 當主訊號、polling 當 fallback。Webhook 為單次交付 —— production 程式碼應在 webhook 未於可接受時間內抵達時,改用 polling 補上。

在 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)。

GET /v1/offers/{offerId}/credentials 回該 offer 已發出的憑證。在 webhook 不可用(X.509 路徑、notarize_on_iota=false)、或 webhook 未到、或想隨時做一次同步狀態查詢時使用。

Terminal window
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 }
]
欄位值意義
statusACTIVE / SUSPENDED / REVOKED / EXPIRED / DELETED憑證 lifecycle
on_chain_statusPENDING / IN_PROGRESS / COMPLETED / FAILED / nullNotarization 進度。終局狀態為 COMPLETED 與 FAILED。憑證未上鏈時為 null。
object_idstring / nullIOTA object id;僅在 on_chain_status 為 COMPLETED 時有值
blockchainIOTA / null錨點網路(此處為大寫;webhook payload 用小寫 iota)。憑證未上鏈時為 null。
狀態原因
400offerId 不是合法 UUID
401缺 X-API-Key 或 key 無效
404Offer 不存在,或不屬於這支 API key(兩種情況故意無法區分)

Credential Issuer 的這組端點可以列出、查詢、撤銷、暫停與恢復你的 tenant 發出的憑證。全部都用 X-API-Key 帶 Issuer API key,且只看得到自己 tenant 的憑證:憑證不存在與憑證屬於其他 tenant 都回 404。這裡的 credential_id 與 polling 端點、webhook 回的是同一個值。

MethodPath用途
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
Terminal window
curl "https://issuer.turingspace.co/v1/credentials?status=ACTIVE&limit=20" \
-H "X-API-Key: tcs_production_<your-api-key>"

結果依 issued_at 由新到舊排序。

Query param型別說明
statusstring依狀態篩選:ACTIVE、REVOKED、EXPIRED、DELETED 或 SUSPENDED。要比對多個狀態就重複帶這個參數。
config_idstring完全比對 credential configuration ID
vctstring完全比對 VCT
issued_afterstringISO 8601 日期。發出時間在此時間(含)之後的憑證。
issued_beforestringISO 8601 日期。發出時間嚴格早於此時間的憑證。必須晚於 issued_after,且兩者間隔不得超過 90 天。
qstring對 credential_id 或 holder_did 做不分大小寫的子字串搜尋
offsetinteger略過的筆數。預設 0,最小 0。
limitinteger回傳筆數。預設 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。

GET /v1/credentials/{credential_id} 回傳一筆,欄位與列表項目相同,另外多出:

欄位型別說明
issuer_didstring / nullIssuer DID
notarized_atstring / null憑證完成鏈上錨點的時間(ISO 8601)
on_chain_statusstring / null值與 Polling 段相同
object_idstring / null鏈上 object id
blockchainstring / null錨點網路(IOTA)
raw_claimsobjectSD-JWT 解碼後的 JWT payload。_sd 項目是 disclosure 的 hash,不是 claim 值。憑證無法解析時為空物件。
Terminal window
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 就已經更新。

動作允許的起始狀態結果
revokeACTIVE、SUSPENDEDREVOKED,並寫入 revoked_at。永久生效:撤銷後不能再暫停或恢復。
suspendACTIVESUSPENDED。revoked_at 維持空值。
reinstateSUSPENDEDACTIVE

憑證有 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 開頭。

TCS 在簽出 SD-JWT VC 之外,可以把每張憑證同步發布到 IOTA Tangle。鏈上 object 儲存 issuer 簽過的 JWT,任何人拿到 object_id 就有一份長期、可由第三方獨立驗證的紀錄 —— 不依賴 TCS 或 issuer 的線上可用性。多數 TCS 客戶採用此模式,也是平台預設。

  • 公部門或合規場景,需要憑證在簽發後多年仍可稽核。
  • 跨組織憑證,需要在不呼叫 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:*truetrue(預設)或 false 略過上鏈
X.509 / x5cfalse僅可設 false(預設)—— 明確設 true 會在 offer 建立時回 400

Offer 一旦建立,credential 請求無法再改變結果。

鏈上 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。

鏈上 object 儲存的是 issuer 簽過的 JWT(header.payload.signature —— SD-JWT VC 的簽章部分,未附加 disclosures)。要在不依賴 TCS 的情況下驗證:

  1. 從 webhook payload 或 GET /v1/offers/{offerId}/credentials 取得憑證的 object_id。
  2. 在對應網路(testnet / mainnet)的 IOTA Notarization explorer 上解析該 object —— state 欄位就是 JWT bytes。
  3. 解析 issuer DID(did:iota:...),對 DID Document 上的驗證方法驗章。

成功解析 + 驗章即為獨立證明:issuer 在鏈上 object 建立的時間點確實簽出了該張憑證。

鏈上 object 原則上可解(unpublish notarization 交易),但目前未公開 API。若需移除特定 object_id(例如隱私 / 個資刪除請求),請聯絡 TCS 團隊並提供 credential_id 與 object_id。同步參見 架構 · 合規與資料處理 · 當事人刪除權。


本頁的 offer 都使用預授權碼流程 — Issuer 在離線端認證 holder(例如在你產品內),然後把一次性的 pre-auth code 嵌進 offer。這是最簡單、也是保管模式採用的方式。