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

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

驗證方收到憑證時,會對照 Trust Registry 的已核准發行方清單檢查 iss 聲明,確保每張憑證都能追溯至登錄清單上的組織。
第一步:取得帳號
Section titled “第一步:取得帳號”如需開通帳號,請聯絡 help@turingspace.co。
你的帳號附帶兩組互不相同的憑證,且不可互換:
- API key —— 你以機器身分呼叫時的常規認證方式,用於
POST /v1/offers與POST /v1/verifier/authorization-request的X-API-Keyheader。 - 你的帳號識別碼(帳號 UUID 或註冊時的 email)與密碼 —— 可換取短期 access token,僅用於 DID 管理(下方
POST /v1/auth/login,接著/v1/did/*)。
第二步:登入
Section titled “第二步:登入”以你的帳號識別碼和密碼換取以 ES256 簽章的 JWT access token,有效期一小時。Trust Registry 對此端點限制每 60 秒最多 5 次嘗試。
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。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
identifier | string | 是 | 你的帳號 UUID 或註冊時的 email |
password | string | 是 | 你的帳號密碼 |
第三步:建立 DID
Section titled “第三步:建立 DID”建立一個錨定在 IOTA 網路上的新 DID(去中心化識別符)。傳送空 body,並在 Authorization header 中帶入你的 JWT。
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,無需生成新的金鑰素材。
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)"}| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
did | string | 是 | 完整的 IOTA DID |
private_key | string | 是 | DID 對應的 Base64url 編碼 Ed25519 私鑰 |
DID 管理
Section titled “DID 管理”你有兩種方式建立 DID 身份:
| 建立(POST /v1/did) | 匯入(POST /v1/did/import) | |
|---|---|---|
| 使用時機 | 從零開始,尚無現有 DID | 你已在 IOTA 上擁有 DID |
| 金鑰生成 | TCS 生成 Ed25519 金鑰對 | 你提供現有的私鑰 |
| 網路互動 | TCS 在 IOTA 上錨定新的 DID 文件 | TCS 驗證 IOTA 上是否存在該 DID |
| 金鑰保管 | 你接收並儲存私鑰 | 你已持有私鑰 |
兩種情況下,DID 都會在 Trust Registry 中登記並與你的組織帳號連結。建立憑證 offer 時,你以此 DID 作為發行方身份。
查詢你的 DID
Section titled “查詢你的 DID”GET /v1/did 回傳你的帳號最近建立、且狀態為 active 的 DID。請在 Authorization header 中帶入你的 JWT。
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。
DID Configuration
Section titled “DID Configuration”Trust Registry 為每個租戶公開 Well-Known DID Configuration 端點。這遵循 DIF Well Known DID Configuration 規範,讓外部各方可驗證你的網域與 DID 之間的連結。
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
Section titled “Schema Registry”Schema Registry 為 TCS 支援的所有憑證類型提供 VCT(Verifiable Credential Type)元資料服務。它是一個唯讀的探索服務 — 你查詢它以了解憑證類型的結構,在發行或驗證前做好準備。

發行方和驗證方都從 Schema Registry 參考 VCT 元資料:發行方用它在發行前驗證憑證 offer;驗證方用它在 presentation 驗證期間了解憑證結構。所有憑證類型在發行前必須完成登記。
列出憑證類型
Section titled “列出憑證類型”GET /schemas 以分頁方式回傳憑證類型清單。此端點為公開,無需身份驗證。
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_by | updated_at 或 created_at。預設 updated_at |
order | asc 或 desc。預設 desc |
status | 依生命週期狀態篩選(例如 active) |
type | 依憑證類型篩選(部分比對,不分大小寫) |
name | 依憑證名稱篩選(部分比對,不分大小寫) |
查詢參數不合法時回 400。
探索憑證類型
Section titled “探索憑證類型”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 欄位相符) |
version | Schema 版本,格式為 v<N>(例如 v2) |