身份驗證

概覽

TCS 根據你呼叫的端點使用三種身份驗證方式：

API Key — 在 X-API-Key header 中傳送的靜態金鑰。用於發行方和驗證方的管理操作。
Bearer JWT — 在 Authorization header 中傳送的 access token。用於 Trust Registry DID 操作和憑證請求。
DPoP（Demonstrating Proof-of-Possession） — RFC 9449 的持有證明機制，將 access token 綁定至客戶端的金鑰對，防範 token 竊取和重播。DPoP 是逐 token 決定的、不是部署層級的全域旗標 —— 個別 /credential 請求是否必須使用 DPoP，取決於 issuer 的簽章 profile 與 token 類型，不是一個全域開關。HAIP v1（X.509 / ES256 issuer）強制要求；EdDSA / DID 路徑為選用。詳見下方端點對照表。

大多數探索和協定端點為公開端點，無需身份驗證。

Rendering diagram...

1. API Key 身份驗證

curl -X POST https://issuer.turingspace.co/v1/offers \
  -H "X-API-Key: tcs_production_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "config_id": "TuringCerts_Standard_Credential_v2_sd_jwt",
      "claims": { "credentialName": "University Degree" }
    },
    "flow": "pre-authorized"
  }'

在 X-API-Key header 中傳送你的 API 金鑰。組織透過 Trust Registry onboarding 由 TCS 團隊處理 — 沒有 self-service apply API，請聯絡我們註冊。核准後即可取得 API 金鑰。伺服器在儲存前以 SHA-256 對你的金鑰進行雜湊處理 — 明文金鑰永不持久化。

詳情	值
Header	`X-API-Key: {your_api_key}`
格式	`tcs_{environment}_{48-hex}`（例如 `tcs_production_...`）
取得方式	Trust Registry onboarding（由 TCS 團隊處理）
儲存方式	僅儲存 SHA-256 雜湊值；明文不儲存
範圍	發行方管理操作、驗證方管理操作

需要 API Key 的端點

方法	端點	服務
POST	`/v1/offers`	Credential Issuer
POST	`/v1/verifier/authorization-request`	Verifier Service
GET	`/v1/verifier/result/:sessionId`	Verifier Service

錯誤回應

狀態碼	訊息	原因
401	`API Key is required`	缺少 `X-API-Key` header
401	`Invalid API Key`	金鑰未找到或雜湊不符
401	`Account is not approved`	金鑰有效但帳號等待核准中

2. Bearer JWT 身份驗證

# Trust Registry DID 操作（來自登入的 token）
curl -X POST https://trust-registry.turingspace.co/v1/did \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{ "did": "did:key:z6Mk..." }'

# 憑證請求（來自 token 端點的 token）
curl -X POST https://issuer.turingspace.co/credential \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "credential_configuration_id": "EmployeeCredential_sd_jwt",
    "proofs": {
      "jwt": ["eyJhbGciOiJFZERTQSIs...proof-jwt"]
    }
  }'

在 Authorization: Bearer {token} header 中傳送 access token。根據操作不同，有兩個不同的 JWT 來源：

用途	Token 來源	取得方式
Trust Registry DID 操作	登入 token	`POST /v1/auth/login` 傳送 uuid 和密碼
憑證請求	Access token	`POST /v1/token` 傳送預授權碼

需要 Bearer JWT 的端點

方法	端點	服務	Token 來源
POST	`/v1/did`	Trust Registry	登入 token
POST	`/v1/did/import`	Trust Registry	登入 token
POST	`/credential`	Credential Issuer	Token 端點

錯誤回應

狀態碼	訊息	原因
401	`invalid_token`	Access token 無效或已過期
403	`Forbidden`	帳號未取得此操作的授權

3. DPoP（Demonstrating Proof-of-Possession）

# 第一步：建立 DPoP proof JWT
# Header
{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": { /* sender's public key */ }
}
# Payload
{
  "jti": "unique-id-abc123",
  "htm": "POST",
  "htu": "https://issuer.turingspace.co/credential",
  "iat": 1711411200,
  "ath": "fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo"
}

# 第二步：同時傳送兩個 header
curl -X POST https://issuer.turingspace.co/credential \
  -H "Authorization: DPoP eyJhbGciOiJFUzI1NiJ9..." \
  -H "DPoP: eyJ0eXAiOiJkcG9wK2p3dCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "credential_configuration_id": "EmployeeCredential_sd_jwt",
    "proofs": {
      "jwt": ["eyJhbGciOiJFZERTQSIs...proof-jwt"]
    }
  }'

DPoP（RFC 9449）將 access token 綁定至客戶端的金鑰對，讓被竊取的 token 無法被其他人使用。HAIP v1 要求，建議所有憑證端點互動都使用。需要兩個 header：Authorization: DPoP {access_token} 和 DPoP: {proof_jwt}。

DPoP Proof JWT 結構

Header：

欄位	值	說明
`typ`	`dpop+jwt`	DPoP proof 的固定類型
`alg`	`ES256` 或 `EdDSA`	簽名演算法
`jwk`	`{ ... }`	傳送方的 JWK 格式公鑰

Payload：

欄位	必填	說明
`jti`	是	重播保護用的唯一識別符
`htm`	是	請求的 HTTP 方法（例如 `POST`）
`htu`	是	請求的 HTTP URL（不含查詢字串和片段）
`iat`	是	發行時間戳（Unix epoch 秒）
`ath`	是	access token 的 Base64url 編碼 SHA-256 雜湊值
`nonce`	條件性	伺服器提供的 nonce，收到 `DPoP-Nonce` header 後必須提供

驗證參數

參數	值
支援演算法	`EdDSA`、`ES256`
Nonce 到期時間	300 秒
JTI 到期時間	300 秒
IAT 最大期限	300 秒
時鐘偏差容忍	60 秒（向未來）

DPoP Nonce 流程

當伺服器要求 nonce 時，遵循以下交換流程：

Rendering diagram...

傳送不含 nonce 欄位的 DPoP proof 請求。
伺服器回傳 HTTP 400，錯誤碼 use_dpop_nonce 及 DPoP-Nonce 回應 header。
以 DPoP-Nonce header 的值作為 nonce 欄位重新建構 DPoP proof JWT。
以更新後的 DPoP proof 重試請求。

錯誤回應

狀態碼	錯誤碼	原因
400	`invalid_dpop_proof`	DPoP proof 結構、簽名或 `ath` 驗證失敗
400	`use_dpop_nonce`	伺服器要求 DPoP nonce — 請檢查 `DPoP-Nonce` 回應 header

4. 公開端點（無需身份驗證）

這些端點無需身份驗證。它們提供探索元資料、協定交換和公開註冊服務。

方法	端點	服務
GET	`/v1/offers/:offerId`	Credential Issuer
GET	`/.well-known/openid-credential-issuer/:tenant`	Credential Issuer
GET	`/.well-known/oauth-authorization-server`	Authorization Server
POST	`/v1/token`	Authorization Server
POST	`/v1/nonce`	Credential Issuer
POST	`/v1/par`	Authorization Server
GET	`/v1/authorize`	Authorization Server
POST	`/v1/authorize/submit`	Authorization Server
GET	`/v1/verifier/request/:requestUriId`	Verifier Service
POST	`/v1/verifier/presentation`	Verifier Service
GET	`/schemas/:type/:version`	Schema Registry
POST	`/v1/auth/login`	Trust Registry
GET	`/.well-known/did-configuration.json/:tenant`	Trust Registry

完整端點與驗證對照表

方法	路徑	驗證類型	DPoP 何時必須	服務
POST	`/v1/offers`	API Key	—	Credential Issuer
GET	`/v1/offers/:offerId`	公開	—	Credential Issuer
POST	`/credential`	Bearer JWT 或 DPoP-bound	Issuer 註冊在 HAIP / X.509 / ES256 路徑時必須；EdDSA / DID 路徑為選用	Credential Issuer
GET	`/.well-known/openid-credential-issuer/:tenant`	公開	—	Credential Issuer
GET	`/.well-known/oauth-authorization-server`	公開	—	Authorization Server
POST	`/v1/token`	公開	申請 DPoP-bound access token 時須附 DPoP proof（HAIP 路徑）	Authorization Server
POST	`/v1/nonce`	公開	—	Credential Issuer
POST	`/v1/par`	公開	—	Authorization Server
GET	`/v1/authorize`	公開	—	Authorization Server
POST	`/v1/authorize/submit`	公開	—	Authorization Server
POST	`/v1/verifier/authorization-request`	API Key	—	Verifier Service
GET	`/v1/verifier/result/:sessionId`	API Key	—	Verifier Service
GET	`/v1/verifier/request/:requestUriId`	公開	—	Verifier Service
POST	`/v1/verifier/presentation`	公開	—	Verifier Service
GET	`/schemas/:type/:version`	公開	—	Schema Registry
POST	`/v1/auth/login`	公開	—	Trust Registry
POST	`/v1/did`	Bearer JWT	—	Trust Registry
POST	`/v1/did/import`	Bearer JWT	—	Trust Registry
GET	`/.well-known/did-configuration.json/:tenant`	公開	—	Trust Registry

常見錯誤碼

狀態碼	錯誤	說明
400	`invalid_grant`	預授權碼已過期或已使用
400	`invalid_dpop_proof`	DPoP proof 結構、簽名或 `ath` 驗證失敗
400	`use_dpop_nonce`	伺服器要求 DPoP nonce — 請檢查 `DPoP-Nonce` 回應 header
401	`invalid_token`	Access token 無效或已過期
401	`invalid_token`（DPoP 路徑）	Token 結構有效，但端點要求 DPoP 綁定 —— issuer 註冊於 HAIP / X.509 / ES256 路徑。請改以 `Authorization: DPoP <token>` 加上 `DPoP:` proof header 重發（見 §3）。
401	`API Key is required`	缺少 `X-API-Key` header
401	`Invalid API Key`	API 金鑰未找到或雜湊不符
401	`Account is not approved`	API 金鑰有效但帳號等待核准中
403	`Forbidden`	帳號未取得此操作的授權

下一步

發行憑證 — 使用你的 API 金鑰建立憑證 offer
驗證憑證 — 設定憑證驗證
信任與 Schema 治理 — 完成註冊並取得你的 API 金鑰