191 lines
3.1 KiB
Markdown
191 lines
3.1 KiB
Markdown
# 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
|
||
```json
|
||
{
|
||
"detail": "error_code"
|
||
}
|
||
```
|
||
|
||
常見 `detail`：
|
||
- `invalid_client`（401）
|
||
- `invalid_api_key`（401）
|
||
- `client_expired`（401）
|
||
- `origin_not_allowed`（403）
|
||
- `ip_not_allowed`（403）
|
||
- `path_not_allowed`（403）
|
||
|
||
## Endpoints
|
||
|
||
### GET `/internal/systems`
|
||
Response:
|
||
```json
|
||
{
|
||
"items": [
|
||
{ "id": "uuid", "system_key": "ST20260331X1234", "name": "Marketing", "status": "active" }
|
||
],
|
||
"total": 1,
|
||
"limit": 200,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
### GET `/internal/modules`
|
||
Response:
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "uuid",
|
||
"module_key": "MD20260331X5678",
|
||
"system_key": "ST20260331X1234",
|
||
"name": "Campaign",
|
||
"status": "active"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"limit": 500,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
### GET `/internal/companies`
|
||
Query:
|
||
- `keyword`（optional）
|
||
- `limit`（default 500）
|
||
- `offset`（default 0）
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"items": [
|
||
{ "id": "uuid", "company_key": "CP20260331X9999", "name": "OSE", "status": "active" }
|
||
],
|
||
"total": 1,
|
||
"limit": 500,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
### GET `/internal/sites`
|
||
Query:
|
||
- `company_key`（optional）
|
||
- `limit`（default 500）
|
||
- `offset`（default 0）
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "uuid",
|
||
"site_key": "ST20260331X1111",
|
||
"company_key": "CP20260331X9999",
|
||
"name": "main-site",
|
||
"status": "active"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"limit": 500,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
### GET `/internal/members`
|
||
Query:
|
||
- `keyword`（optional）
|
||
- `limit`（default 500）
|
||
- `offset`（default 0）
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "uuid",
|
||
"user_sub": "authentik-uid",
|
||
"username": "chris",
|
||
"email": "chris@ose.tw",
|
||
"display_name": "Chris",
|
||
"is_active": true
|
||
}
|
||
],
|
||
"total": 1,
|
||
"limit": 500,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
### POST `/internal/users/upsert-by-sub`
|
||
Request:
|
||
```json
|
||
{
|
||
"user_sub": "authentik-uid",
|
||
"username": "chris",
|
||
"email": "chris@ose.tw",
|
||
"display_name": "Chris",
|
||
"is_active": true
|
||
}
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"id": "uuid",
|
||
"user_sub": "authentik-uid",
|
||
"idp_user_id": "idp-user-id-or-uuid",
|
||
"username": "chris",
|
||
"email": "chris@ose.tw",
|
||
"display_name": "Chris",
|
||
"is_active": true
|
||
}
|
||
```
|
||
|
||
### GET `/internal/permissions/{user_sub}/snapshot`
|
||
Response:
|
||
```json
|
||
{
|
||
"user_sub": "authentik-uid",
|
||
"permissions": [
|
||
{
|
||
"scope_type": "site",
|
||
"scope_id": "ST20260331X1111",
|
||
"system": "ST20260331X1234",
|
||
"module": "MD20260331X5678",
|
||
"actions": ["view", "edit"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### POST `/internal/idp/users/ensure`
|
||
（相容路徑：`/internal/authentik/users/ensure`）
|
||
Request:
|
||
```json
|
||
{
|
||
"user_sub": "authentik-uid",
|
||
"email": "user@example.com",
|
||
"username": "user1",
|
||
"display_name": "User One",
|
||
"is_active": true
|
||
}
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{
|
||
"idp_user_id": "idp-user-id-or-uuid",
|
||
"action": "created"
|
||
}
|
||
```
|
||
|
||
`action` 可能值：`created` / `updated`
|