101 lines
2.2 KiB
Markdown
101 lines
2.2 KiB
Markdown
# 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:
|
||
```json
|
||
{
|
||
"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`
|
||
```json
|
||
{
|
||
"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`
|
||
```json
|
||
{
|
||
"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 /admin/systems`
|
||
- `GET/POST /admin/modules`
|
||
- `GET/POST /admin/companies`
|
||
- `GET/POST /admin/sites`
|
||
- `GET /admin/members`
|
||
|
||
## 4. 權限群組（一組權限綁多個 user）
|
||
Headers:
|
||
- `X-Client-Key`
|
||
- `X-API-Key`
|
||
|
||
- `GET/POST /admin/permission-groups`
|
||
- `POST /admin/permission-groups/{group_key}/members/{authentik_sub}`
|
||
- `DELETE /admin/permission-groups/{group_key}/members/{authentik_sub}`
|
||
- `POST /admin/permission-groups/{group_key}/permissions/grant`
|
||
- `POST /admin/permission-groups/{group_key}/permissions/revoke`
|
||
|
||
群組授權 payload 與 user 授權 payload 相同（用 `system/module/scope/action`）。
|
||
|
||
## 5. 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`
|
||
|
||
## 6. 常見錯誤
|
||
- `401 invalid_client`
|
||
- `401 invalid_api_key`
|
||
- `401 invalid_internal_secret`
|
||
- `404 system_not_found`
|
||
- `404 company_not_found`
|
||
- `404 site_not_found`
|