信任與 Schema 治理

前置條件

這通常是你 TCS 整合的第一步。你需要：

• 組織名稱和聯絡電子郵件
• 安全密碼（至少 8 個字元，含大寫 + 小寫 + 數字）
• 你的組織的唯一租戶識別符

什麼是 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 聲明，確保每張憑證都能追溯至已登記的受審核實體。

註冊流程

第一步：申請加入（線下）

Trust Registry onboarding 由 TCS 團隊處理，不開放公開 API — Trust Registry 是 root of trust，核准需經過身份審核。組織註冊步驟：

1. 聯絡我們，提供組織名稱、希望使用的 tenant slug（小寫字母 / 數字 / 連字號，3–32 字元，例如 acme-corp）、以及負責整合的工程窗口 email。
2. 我們審核並在 Trust Registry 上建立你的帳號。
3. 你會收到 兩組互不相同的憑證，透過加密通道線下交付一次：
   • UUID + 初始密碼 —— 用於 Trust Registry 登入（下方 POST /v1/auth/login）以及 DID 生命週期端點（/v1/did/*）。
   • 另一組 Issuer API key —— 用於 POST /v1/offers 與 POST /v1/verifier/authorization-request 的 X-API-Key header。
4. 兩組憑證不可互換；以 tenant 為 key 存進 secret manager 是最簡單的模式。

妥善保存憑證

UUID、密碼與 Issuer API key 只會交付一次。請放進你的 secret manager / KMS，以 tenant 為 key 保存。任何一者都不要 commit 進原始碼。

第二步：登入

以你的 UUID 和密碼換取 JWT access token。Trust Registry 對此端點限制每 60 秒最多 5 次嘗試。

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

成功（200 OK）：

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJpYXQiOjE3MTk0MDAwMDAsImV4cCI6MTcxOTQ4NjQwMH0.signature",
  "expires_in": 86400
}

錯誤（401 Unauthorized）：

{
  "statusCode": 401,
  "message": "Invalid credentials"
}

錯誤（403 Forbidden）：

{
  "statusCode": 403,
  "message": "Account not approved"
}

參數	類型	必填	說明
uuid	string	是	申請步驟回傳的 UUID
password	string	是	註冊時設定的密碼

第三步：建立 DID

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

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

成功（201 Created）：

{
  "did": "did:iota:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "private_key": "OKP.Ed25519.eyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5IiwiZCI6Ijk4..."
}

請儲存你的私鑰

private_key 僅顯示一次。請將其儲存至 secrets manager 或加密保險庫，你需要此金鑰來簽名憑證。

錯誤（401 Unauthorized）：

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

錯誤（500 Internal Server Error）：

{
  "statusCode": 500,
  "message": "IOTA network error"
}

第四步：匯入現有 DID（替代方案）

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

curl -X POST https://trust-registry.turingspace.co/v1/did/import \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJpYXQiOjE3MTk0MDAwMDAsImV4cCI6MTcxOTQ4NjQwMH0.signature" \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:iota:0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
    "private_key": "OKP.Ed25519.eyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5IiwiZCI6ImFi..."
  }'

成功（201 Created）：

{
  "did": "did:iota:0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
  "status": "imported"
}

錯誤（400 Bad Request）：

{
  "statusCode": 400,
  "message": "Invalid format or verification failed"
}

錯誤（404 Not Found）：

{
  "statusCode": 404,
  "message": "DID not found on IOTA network"
}

錯誤（409 Conflict）：

{
  "statusCode": 409,
  "message": "DID already imported"
}

錯誤（503 Service Unavailable）：

{
  "statusCode": 503,
  "message": "IOTA network unavailable"
}

參數	類型	必填	說明
did	string	是	完整的 IOTA DID
private_key	string	是	DID 對應的 Base64url 編碼 Ed25519 私鑰

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 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": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://identity.foundation/.well-known/did-configuration/v1"
      ],
      "type": ["VerifiableCredential", "DomainLinkageCredential"],
      "issuer": "did:iota:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "issuanceDate": "2025-01-15T09:00:00Z",
      "credentialSubject": {
        "id": "did:iota:0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "origin": "https://trust-registry.turingspace.co"
      }
    }
  ]
}

此端點為公開，無需身份驗證。錢包和驗證方使用它確認 DID 由運作該網域的實體所控制。

Schema Registry

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

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

探索憑證類型

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.",
  "claims": [
    {
      "path": ["given_name"],
      "display": [{ "lang": "en-US", "label": "Given Name" }],
      "sd": "allowed"
    },
    {
      "path": ["family_name"],
      "display": [{ "lang": "en-US", "label": "Family Name" }],
      "sd": "allowed"
    }
  ],
  "schema_uri": "https://schema-registry.turingspace.co/schemas/TuringCerts_Standard_Credential/v2"
}

錯誤（404 Not Found）：

{
  "statusCode": 404,
  "message": "VCT not found"
}

路徑參數	說明
type	憑證類型識別符（與已發行 SD-JWT VC 中的 vct 欄位相符）
version	Schema 版本號（例如 1.0）

Schema Registry 為唯讀

Schema Registry 是現行可用憑證類型的唯一事實來源 —— 請至 完整目錄 檢視最新清單。若要為你的組織提案新的憑證類型，請聯繫 TCS 團隊。

下一步

• 發行憑證 — 使用你的 API 金鑰和 DID 發行 SD-JWT 憑證
• 驗證憑證 — 驗證憑證 presentation
• 身份驗證參考 — 了解所有身份驗證模式