member_center/docs/OPENAPI.md

OpenAPI 草案（完整）

已補上完整端點與資料結構，並提供 docs/openapi.yaml 作為可直接擴充的版本。

版本

• OpenAPI: 3.1.0
• 檔案：docs/openapi.yaml

核心資源

• OAuth2/OIDC：授權、token、discovery、JWKS
• Auth：註冊、登入（password grant）、刷新、登出、忘記/重設密碼、Email 驗證
• User：個人資料
• Newsletter：訂閱/確認/退訂/偏好
• Admin：Tenants/Lists/OAuth Clients（MVP CRUD）

Security Schemes

• OAuth2 (Authorization Code + PKCE)
• Bearer JWT（API 使用）

補充說明

• /oauth/token、/auth/login、/auth/refresh 使用 application/x-www-form-urlencoded
• /auth/email/verify 需要 token + email
• /newsletter/subscribe 會回傳 confirm_token
• /newsletter/unsubscribe-token 需要 list_id + email 才能申請 unsubscribe_token
• /newsletter/preferences（GET/POST）需要 list_id + email，避免跨租戶資料讀取/更新

通用欄位

• occurred_at：RFC3339（例：2026-02-10T09:30:00Z）
• event_id、request_id：UUID

通用錯誤格式

{
  "error": "string_code",
  "message": "human readable message",
  "request_id": "uuid"
}

多租戶資料隔離原則

• 與訂閱者資料（preferences、unsubscribe token）相關的查詢與寫入，一律必須帶 list_id + email 做租戶邊界約束。
• 不提供僅靠 email 或單純 subscription_id 的公開查詢/操作端點。

Webhook Auth（Member Center -> Send Engine）

• Header（對齊 Send Engine 規格）：
  • X-Signature
  • X-Timestamp
  • X-Nonce
  • X-Client-Id
• X-Client-Id 來源：
  • 由 Send Engine 的 auth_clients.id（UUID）提供
  • Member Center 以 SendEngine__TenantWebhookClientIds__{tenant_uuid} 設定每個租戶的對應值
• 簽章建議：
  • HMAC-SHA256(secret, "{raw_body}")（對齊 Send Engine 驗證器）
• 驗證規則：
  • timestamp 在允許時間窗（例如 ±5 分鐘）
  • nonce 不可重複（防重放）
  • X-Client-Id 必須存在且 active，且 tenant 綁定一致
  • signature 必須匹配

OAuth Client 用途分離（強制）

• usage=tenant_api：
  • 供租戶站台拿 token 呼叫 Member Center / Send Engine API
  • scope 僅給業務所需（如 newsletter:send.write、newsletter:list.read）
• usage=webhook_outbound：
  • 供 Member Center 內部標記「對外 webhook 用」的租戶憑證用途
  • 不可用於租戶 API 呼叫
  • X-Client-Id 仍以 Send Engine auth_clients.id 為準
• 管理規則：
  • 每個 tenant 至少 2 組憑證（tenant_api / webhook_outbound）
  • secret 分開輪替，禁止共用

待新增 API / Auth（規劃中）

API

• GET /newsletter/subscriptions?list_id=...：回傳清單內所有訂閱（供發送引擎同步用）
• POST /webhooks/subscriptions：Member Center → Send Engine 事件推送（Send Engine 端點，scope: newsletter:events.write）
• POST /webhooks/lists/full-sync：Member Center → Send Engine 全量同步（Send Engine 端點，scope: newsletter:events.write）
• POST /api/subscriptions/disable：Send Engine → Member Center 黑名單回寫（全租戶 email，scope: newsletter:events.write）

Auth / Scope

• OAuth Client 需綁定 tenant_id
• 新增 scope：
  • newsletter:list.read
  • newsletter:events.read
  • newsletter:events.write
• 發送引擎僅能用上述 scope，禁止 admin 權限