跳到內容
Turing Space TCS

API 參考

概覽

Section titled “概覽”

本頁列出 TCS 公開的所有公開和管理端點。服務間內部通訊使用的端點不包含在內。所有服務均提供健康檢查端點（GET /health），但不列入本參考文件。

各端點的身份驗證詳情，請參閱身份驗證參考文件。

OpenAPI 規格

Section titled “OpenAPI 規格”

若你需要 machine-readable spec 來產生 SDK 或自動化工具，請聯繫 TCS 團隊。

服務端點

Section titled “服務端點”

基礎 URL：https://auth.turingspace.co

Authorization Server 處理 OAuth 2.0 token 發行、DPoP 驗證和授權碼流程。它依照 RFC 8414 發布探索元資料。

方法路徑說明驗證
GET/.well-known/oauth-authorization-serverRFC 8414 探索文件。回傳 issuer、token_endpoint、pushed_authorization_request_endpoint 和 dpop_signing_alg_values_supported 等欄位。公開
POST/v1/token以預授權碼或授權碼換取 access token。公開
POST/v1/par建立 Pushed Authorization Request session（RFC 9126）。公開

授權端點（GET /v1/authorize）、登入表單提交（POST /v1/authorize/submit）以及登出端點（GET /end_session）皆為瀏覽器導引（browser-driven），不屬於整合 API 表面。為符合規範，它們仍會出現在 discovery 文件中。

GET /.well-known/oauth-authorization-server — RFC 8414 AS 元資料探索

回傳 Authorization Server 元資料文件。錢包和客戶端在啟動時取得此文件，以探索端點 URL、支援的授權類型、DPoP 演算法和客戶端 attestation 要求。

驗證： 公開 · Content-Type： N/A（GET）

Response 200

{
  "issuer": "https://auth.turingspace.co",
  "authorization_endpoint": "https://auth.turingspace.co/v1/authorize",
  "token_endpoint": "https://auth.turingspace.co/v1/token",
  "pushed_authorization_request_endpoint": "https://auth.turingspace.co/v1/par",
  "end_session_endpoint": "https://auth.turingspace.co/end_session",
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "urn:ietf:params:oauth:grant-type:pre-authorized_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["attest_jwt_client_auth"],
  "client_attestation_signing_alg_values_supported": ["ES256", "EdDSA"],
  "client_attestation_pop_signing_alg_values_supported": ["ES256", "EdDSA"],
  "dpop_signing_alg_values_supported": ["ES256", "EdDSA"],
  "authorization_details_types_supported": ["openid_credential"],
  "authorization_response_iss_parameter_supported": true,
  "id_token_signing_alg_values_supported": ["ES256"]
}

錯誤 — 正常操作下不預期有錯誤。永遠回傳 200。

另見： 身份驗證參考

POST /v1/par — 建立 PAR session（RFC 9126）

將授權請求推送至 AS 並取得 request_uri 憑證。錢包接著將使用者重新導向至 AS 的授權端點並帶上此憑證。這是授權碼發行流程的第一步；pre-authorized_code 流程完全略過 PAR。

驗證： 公開 · Content-Type： application/x-www-form-urlencoded

預設要求客戶端 attestation。 AS 的 CLIENT_ATTESTATION_REQUIRED_AUTH_CODE=true。請在請求中加入 OAuth-Client-Attestation + OAuth-Client-Attestation-PoP 標頭，否則會以 401 拒絕。詳情請見身份驗證。

請求參數

  • response_type（required, string）— 必須為 code。
  • client_id（required, string）— 客戶端識別符，例如 test-wallet。
  • redirect_uri（required, URL）— 授權碼傳遞 URL，例如 https://wallet.example.com/callback。
  • code_challenge（required, string）— PKCE challenge：base64url(SHA-256(code_verifier))，例如 E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM。
  • code_challenge_method（required, string）— 必須為 S256。
  • scope（optional, string）— 依 HAIP §4.3 的 Credential configuration ID，例如 TuringCerts_Standard_Credential_v2_sd_jwt。
  • issuer_state（optional, UUID）— 從憑證 offer 的 authorization_code.issuer_state 帶入。
  • authorization_details（optional, JSON array）— RFC 9396 / OID4VCI §5.1.1，例如 [{"type":"openid_credential","credential_configuration_id":"UniversityDegree"}]。
  • state（optional, string ≤ 4096 chars）— 錢包 CSRF token。
  • request_uri — PAR body 中禁止使用（RFC 9126 §2.1）；以 invalid_request 拒絕。

Response 201

{
  "request_uri": "urn:ietf:params:oauth:request-uri:bwc4JZ-ESnd0kX1aIAr5pg",
  "expires_in": 60
}

錯誤 — { "error": "...", "error_description": "..." }（RFC 6749 §5.2）

  • 400 invalid_request — 缺少必要欄位、body 中帶有 request_uri，或 issuer_state 不是合法 UUID。

另見： 錢包協議 — 憑證發行流程

POST /v1/token — 以授權碼換取 access token

以預授權碼（pre-authorized_code grant）或授權碼（authorization_code grant）換取 access token。Token 回應攜帶 Bearer 或 DPoP 綁定的 access token，用於憑證端點。

驗證： 公開 · Content-Type： application/x-www-form-urlencoded

請求參數 — pre-authorized_code grant

  • grant_type（required, string）— urn:ietf:params:oauth:grant-type:pre-authorized_code。
  • pre-authorized_code（required, string）— 來自憑證 offer 的授權碼，例如 SplxlOBeZQQYbYS6WxSbIA。
  • tx_code（conditional, string）— 若 offer 中帶有 tx_code，則需提供交易碼（使用者 PIN），例如 123456。

請求參數 — authorization_code grant

  • grant_type（required, string）— authorization_code。
  • code（required, string）— 來自重新導向回呼的授權碼。
  • code_verifier（required, string）— PKCE verifier，例如 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk。
  • redirect_uri（required, string）— 必須與 PAR session 中的 URI 相符。
  • client_id（required, string）— 客戶端識別符。

Response 200

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "DPoP",
  "expires_in": 3600
}

token_type 在請求包含 DPoP 標頭時為 DPoP，否則為 Bearer。

錯誤 — { "error": "...", "error_description": "..." }（RFC 6749 §5.2）

  • 400 invalid_grant — 預授權碼已過期或已使用。
  • 400 unsupported_grant_type — 未知的 grant_type 值。
  • 400 use_dpop_nonce — AS 要求新的 DPoP nonce；請重試並帶上 DPoP-Nonce 標頭。
  • 400 invalid_dpop_proof — DPoP proof JWT 格式錯誤或已過期。

另見： 錢包協議 — token 換取

下一步

Section titled “下一步”