member-platform/docs/INTERNAL_API_HANDOFF.md

Internal API Handoff（新模型）

Base URL

• Local: http://127.0.0.1:8000
• Prod: 由部署環境提供

Auth Headers（/internal/*）

• X-Client-Key: <client_key>
• X-API-Key: <api_key>

Common Error Response

{ "detail": "error_code" }

已實作端點

1. GET /internal/companies
2. GET /internal/sites
3. GET /internal/systems
4. GET /internal/roles
5. GET /internal/members
6. POST /internal/users/upsert-by-sub
7. GET /internal/users/{user_sub}/roles
8. GET /internal/permissions/{user_sub}/snapshot（相容路徑，回 role 聚合資料）
9. POST /internal/provider/users/ensure
10. POST /internal/idp/users/ensure（舊路徑相容，不建議新串接使用）
11. POST /internal/keycloak/users/ensure（舊路徑相容，不建議新串接使用）

角色聚合回應（GET /internal/users/{user_sub}/roles）

{
  "user_sub": "xxxxxxxx",
  "roles": [
    {
      "site_key": "ST20260402X1234",
      "site_display_name": "OSE Main",
      "company_key": "CP20260402X5678",
      "company_display_name": "OSE",
      "system_key": "SY20260402X0001",
      "system_name": "Marketing",
      "role_key": "RL20260402X0002",
      "role_name": "campaign_edit"
    }
  ]
}

注意事項

• 不提供 user direct role 寫入 API。
• User 最終角色由 user_sites + site_roles 推導。