member-platform/docs/FRONTEND_API_CONTRACT.md

Frontend API Contract（memberapi）

Base URL：https://memberapi.ose.tw

0. OIDC 登入

• GET /auth/oidc/url?redirect_uri=...
• POST /auth/oidc/exchange

1. 使用者資訊

• GET /me
• GET /me/permissions/snapshot

permissions item:

{
  "scope_type": "company|site",
  "scope_id": "company_key_or_site_key",
  "system": "mkt",
  "module": "mkt.campaign",
  "action": "view"
}

2. 權限（User 直接授權）

Headers:

• X-Client-Key
• X-API-Key

POST /admin/permissions/grant

{
  "authentik_sub": "authentik-sub",
  "email": "user@example.com",
  "display_name": "User",
  "scope_type": "company",
  "scope_id": "ose-main",
  "system": "mkt",
  "module": "campaign",
  "action": "view"
}

POST /admin/permissions/revoke

{
  "authentik_sub": "authentik-sub",
  "scope_type": "site",
  "scope_id": "tw-main",
  "system": "mkt",
  "module": "campaign",
  "action": "view"
}

說明：

• module 可省略，代表系統層權限，後端會使用 system.__system__。
• module 有值時會組成 {system}.{module} 存入（例如 mkt.campaign）。

3. 主資料管理（admin）

Headers:

• X-Client-Key

• X-API-Key

• GET/POST/PATCH /admin/systems

• GET/POST/PATCH /admin/modules

• GET/POST/PATCH /admin/companies

• GET/POST/PATCH /admin/sites

• GET /admin/members

• POST /admin/members/upsert

• PATCH /admin/members/{authentik_sub}

4. 會員與群組關聯（由會員頁管理）

Headers:

• X-Client-Key

• X-API-Key

• GET /admin/members/{authentik_sub}/permission-groups

• PUT /admin/members/{authentik_sub}/permission-groups

{
  "group_keys": ["site-ops", "mkt-admin"]
}

5. 權限群組（一組權限可綁多個 user）

Headers:

• X-Client-Key

• X-API-Key

• GET/POST/PATCH /admin/permission-groups

• GET /admin/permission-groups/{group_key}/permissions

• POST /admin/permission-groups/{group_key}/permissions/grant

• POST /admin/permission-groups/{group_key}/permissions/revoke

群組授權 payload 與 user 授權 payload 相同（用 system/module/scope/action）。

6. 直接授權列表（權限管理頁）

Headers:

• X-Client-Key

• X-API-Key

• GET /admin/permissions/direct?keyword=&scope_type=&limit=&offset=

• DELETE /admin/permissions/direct/{permission_id}

7. Internal 查詢 API（其他系統）

Headers:

• X-Internal-Secret

• GET /internal/systems

• GET /internal/modules

• GET /internal/companies

• GET /internal/sites

• GET /internal/members

• GET /internal/permissions/{authentik_sub}/snapshot

8. 常見錯誤

• 401 invalid_client
• 401 invalid_api_key
• 401 invalid_internal_secret
• 404 system_not_found
• 404 company_not_found
• 404 site_not_found
• 400 invalid_permission_id