跳到內容

信任與 Schema 治理

Trust Registry 是單一 TCS 部署內的信任根源。組織在能夠在該部署中發行或驗證憑證之前,必須先完成註冊並取得已核准的身份。這確保每張憑證都可追溯至已知、已完成註冊的實體 — 消除匿名發行的可能性。

Trust List in TCS — TCS as Trust Anchor with tenant hierarchy

TCS 採用範圍限定的發行者允許清單(scoped issuer allowlist):每個租戶(例如 Turing Certs)在完成註冊時即加入清單,並由設定使用同一個 Trust Registry 的驗證者所接受。這是刻意採取的中心化治理模式 — 並非 OpenID Federation、EBSI TIR 或 ETSI/eIDAS 信任清單。跨生態系信任(例如將 TCS 發行的憑證呈現給其他生態系的驗證者)需透過 X.509 / x5c 路徑橋接到外部根 CA — 詳見架構與安全及標準合規。

Trust Registry — Issuer trust chain and verifier lookup

驗證方收到憑證時,會對照 Trust Registry 的已核准發行方清單檢查 iss 聲明,確保每張憑證都能追溯至登錄清單上的組織。

如需開通帳號,請聯絡 help@turingspace.co。

你的帳號附帶兩組互不相同的憑證,且不可互換:

  • API key —— 你以機器身分呼叫時的常規認證方式,用於 POST /v1/offers 與 POST /v1/verifier/authorization-request 的 X-API-Key header。
  • 你的帳號識別碼(帳號 UUID 或註冊時的 email)與密碼 —— 可換取短期 access token,僅用於 DID 管理(下方 POST /v1/auth/login,接著 /v1/did/*)。

以你的帳號識別碼和密碼換取以 ES256 簽章的 JWT access token,有效期一小時。Trust Registry 對此端點限制每 60 秒最多 5 次嘗試。

Terminal window
curl -X POST https://trust-registry.turingspace.co/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"identifier": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"password": "SecurePass123"
}'

成功(200 OK):

{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRjcy10ci0xIn0.eyJzdWIiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJ1c2VyX2lkIjoxLCJ0ZW5hbnQiOiJhY21lLXVuaXZlcnNpdHkiLCJpc19pc3N1ZXIiOnRydWUsImlzX3ZlcmlmaWVyIjp0cnVlLCJpc3MiOiJ0Y3MtdHIiLCJpYXQiOjE3MTk0MDAwMDAsImV4cCI6MTcxOTQwMzYwMH0.signature",
"expires_in": 3600,
"token_type": "Bearer"
}

錯誤(401 Unauthorized) — 識別碼或密碼錯誤:

{
"statusCode": 401,
"message": "Invalid uuid or password"
}

尚未核准的帳號同樣回 401,訊息為 Unauthorized。

參數類型必填說明
identifierstring是你的帳號 UUID 或註冊時的 email
passwordstring是你的帳號密碼

建立一個錨定在 IOTA 網路上的新 DID(去中心化識別符)。傳送空 body,並在 Authorization header 中帶入你的 JWT。

Terminal window
curl -X POST https://trust-registry.turingspace.co/v1/did \
-H "Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRjcy10ci0xIn0.eyJzdWIiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJ1c2VyX2lkIjoxLCJ0ZW5hbnQiOiJhY21lLXVuaXZlcnNpdHkiLCJpc19pc3N1ZXIiOnRydWUsImlzX3ZlcmlmaWVyIjp0cnVlLCJpc3MiOiJ0Y3MtdHIiLCJpYXQiOjE3MTk0MDAwMDAsImV4cCI6MTcxOTQwMzYwMH0.signature" \
-H "Content-Type: application/json"

成功(201 Created):

{
"did": "did:iota:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
"key_id": "did:iota:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890#Xh5bQm4n0yJ2kVq8T1pWc7rLs3dZaE9gUoF6iK0jHvY",
"public_key_jwk": {
"kty": "OKP",
"use": "sig",
"key_ops": ["verify", "sign"],
"alg": "EdDSA",
"kid": "Xh5bQm4n0yJ2kVq8T1pWc7rLs3dZaE9gUoF6iK0jHvY",
"crv": "Ed25519",
"x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
},
"private_key": "nwKZ3iFzL7pZJK5pPJ-8k9vXcL2vL7pZJK5pPJ-8k9s"
}

錯誤(401 Unauthorized):

{
"statusCode": 401,
"message": "Unauthorized"
}

錯誤(403 Forbidden) — 帳號尚未核准:

{
"statusCode": 403,
"message": "User account is not approved"
}

錯誤(503 Service Unavailable) — 此部署沒有 IOTA 連線:

{
"statusCode": 503,
"message": "DID management requires an IOTA connection: IOTA is disabled in this deployment (IOTA_ENABLED=false)"
}

錯誤(500 Internal Server Error) — DID 無法發布到 IOTA 網路:

{
"statusCode": 500,
"message": "Internal server error"
}

第四步:匯入現有 DID(替代方案)

Section titled “第四步:匯入現有 DID(替代方案)”

若你的組織已擁有錨定在 IOTA 網路上的 DID,可以匯入而非建立新的。這會在 Trust Registry 中登記該 DID,無需生成新的金鑰素材。

Terminal window
curl -X POST https://trust-registry.turingspace.co/v1/did/import \
-H "Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRjcy10ci0xIn0.eyJzdWIiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJ1c2VyX2lkIjoxLCJ0ZW5hbnQiOiJhY21lLXVuaXZlcnNpdHkiLCJpc19pc3N1ZXIiOnRydWUsImlzX3ZlcmlmaWVyIjp0cnVlLCJpc3MiOiJ0Y3MtdHIiLCJpYXQiOjE3MTk0MDAwMDAsImV4cCI6MTcxOTQwMzYwMH0.signature" \
-H "Content-Type: application/json" \
-d '{
"did": "did:iota:0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
"private_key": "nwKZ3iFzL7pZJK5pPJ-8k9vXcL2vL7pZJK5pPJ-8k9s"
}'

成功(201 Created):

{
"did": "did:iota:0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
"method": "IOTA",
"status": "active"
}

錯誤(400 Bad Request) — 私鑰與該 DID 的任何 verification method 都不相符,或在 IOTA 上解析不到該 DID:

{
"statusCode": 400,
"message": "The provided private key does not match any verification method in the DID Document"
}

私鑰格式錯誤時回 400,訊息為 Invalid private key format。did 不是以 did:iota: 開頭時回 400,訊息為 DID must be a valid IOTA DID (must start with "did:iota:")。

錯誤(403 Forbidden):

{
"statusCode": 403,
"message": "User account is not approved"
}

錯誤(409 Conflict):

{
"statusCode": 409,
"message": "This DID has already been imported"
}

錯誤(503 Service Unavailable) — 此部署沒有 IOTA 連線:

{
"statusCode": 503,
"message": "DID management requires an IOTA connection: IOTA is disabled in this deployment (IOTA_ENABLED=false)"
}
參數類型必填說明
didstring是完整的 IOTA DID
private_keystring是DID 對應的 Base64url 編碼 Ed25519 私鑰

你有兩種方式建立 DID 身份:

建立(POST /v1/did)匯入(POST /v1/did/import)
使用時機從零開始,尚無現有 DID你已在 IOTA 上擁有 DID
金鑰生成TCS 生成 Ed25519 金鑰對你提供現有的私鑰
網路互動TCS 在 IOTA 上錨定新的 DID 文件TCS 驗證 IOTA 上是否存在該 DID
金鑰保管你接收並儲存私鑰你已持有私鑰

兩種情況下,DID 都會在 Trust Registry 中登記並與你的組織帳號連結。建立憑證 offer 時,你以此 DID 作為發行方身份。

GET /v1/did 回傳你的帳號最近建立、且狀態為 active 的 DID。請在 Authorization header 中帶入你的 JWT。

Terminal window
curl https://trust-registry.turingspace.co/v1/did \
-H "Authorization: Bearer <access_token>"

成功(200 OK):

{
"did_url": "did:iota:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
"method": "IOTA",
"status": "active"
}

錯誤: 401(Unauthorized)表示 token 缺少、無效或已過期;403(User account is not approved);404(No active DID found for this account)表示帳號還沒有 DID。

Trust Registry 為每個租戶公開 Well-Known DID Configuration 端點。這遵循 DIF Well Known DID Configuration 規範,讓外部各方可驗證你的網域與 DID 之間的連結。

Terminal window
curl https://trust-registry.turingspace.co/.well-known/did-configuration.json/acme-university

成功(200 OK):

{
"@context": "https://identity.foundation/.well-known/did-configuration/v1",
"linked_dids": [
"eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDppb3RhOjB4YWJjZGVm..."
]
}

linked_dids 的每一筆都是 JWT 形式的 Domain Linkage Credential,租戶的每個 DID 各一筆。此端點為公開,無需身份驗證。錢包和驗證方使用它確認 DID 由運作該網域的實體所控制。

Schema Registry 為 TCS 支援的所有憑證類型提供 VCT(Verifiable Credential Type)元資料服務。它是一個唯讀的探索服務 — 你查詢它以了解憑證類型的結構,在發行或驗證前做好準備。

TCS Schema Registry — Schema governance connecting Issuer and Verifier

發行方和驗證方都從 Schema Registry 參考 VCT 元資料:發行方用它在發行前驗證憑證 offer;驗證方用它在 presentation 驗證期間了解憑證結構。所有憑證類型在發行前必須完成登記。

GET /schemas 以分頁方式回傳憑證類型清單。此端點為公開,無需身份驗證。

Terminal window
curl "https://schema-registry.turingspace.co/schemas?status=active&limit=20"

成功(200 OK):

{
"data": [
{
"name": "University Degree",
"type": "UniversityDegree",
"version": "v1",
"status": "active",
"updated_at": "2026-01-15T08:00:00.000Z"
}
],
"meta": { "offset": 0, "limit": 20, "total": 1 }
}
查詢參數說明
offset略過的筆數。預設 0
limit回傳筆數上限,1–100。預設 20
sort_byupdated_at 或 created_at。預設 updated_at
orderasc 或 desc。預設 desc
status依生命週期狀態篩選(例如 active)
type依憑證類型篩選(部分比對,不分大小寫)
name依憑證名稱篩選(部分比對,不分大小寫)

查詢參數不合法時回 400。

Terminal window
curl https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2

成功(200 OK):

{
"vct": "https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2",
"name": "Turing Certs Standard Credential",
"description": "A general-purpose verifiable credential issued through the Turing Credential Service.",
"status": "active",
"use_case": ["professional_qualification"],
"claims": [
{ "path": ["credentialName"], "mandatory": true },
{ "path": ["expiredTime"], "mandatory": false }
],
"schema": {
"type": "object",
"properties": {
"credentialName": { "type": "string" },
"expiredTime": { "type": "string", "format": "date-time" }
},
"required": ["credentialName"]
},
"updated_at": "2026-01-15T08:00:00.000Z"
}

錯誤(404 Not Found):

{
"statusCode": 404,
"message": "VCT type metadata not found"
}
路徑參數說明
type憑證類型識別符(與已發行 SD-JWT VC 中的 vct 欄位相符)
versionSchema 版本,格式為 v<N>(例如 v2)