member-platform/docs/FRONTEND_API_CONTRACT.md

Frontend API Contract（memberapi）

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

0. 帳號密碼登入

POST /auth/login

Request:

{
  "username": "your-authentik-username",
  "password": "your-password"
}

200 Response:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

401 Response:

{ "detail": "invalid_username_or_password" }

1. 使用者資訊

GET /me

Headers:

• Authorization: Bearer <access_token>

200 Response:

{
  "sub": "authentik-sub-123",
  "email": "user@example.com",
  "display_name": "User Name"
}

401 Error:

{ "detail": "missing_bearer_token" }

或

{ "detail": "invalid_bearer_token" }

2. 我的權限快照

GET /me/permissions/snapshot

Headers:

• Authorization: Bearer <access_token>

200 Response:

{
  "authentik_sub": "authentik-sub-123",
  "permissions": [
    {
      "scope_type": "site",
      "scope_id": "tw-main",
      "module": "campaign",
      "action": "view"
    }
  ]
}

3. Grant 權限

POST /admin/permissions/grant

Headers:

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

Request:

{
  "authentik_sub": "authentik-sub-123",
  "email": "user@example.com",
  "display_name": "User Name",
  "scope_type": "site",
  "scope_id": "tw-main",
  "module": "campaign",
  "action": "view"
}

200 Response:

{
  "permission_id": "uuid",
  "result": "granted"
}

4. Revoke 權限

POST /admin/permissions/revoke

Headers:

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

Request:

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

200 Response:

{
  "deleted": 1,
  "result": "revoked"
}

404 Response:

{ "detail": "user_not_found" }

5. Health Check

GET /healthz

200 Response:

{ "status": "ok" }

6. 常見錯誤碼

• 401 invalid_client
• 401 invalid_api_key
• 401 client_expired
• 403 origin_not_allowed
• 403 ip_not_allowed
• 403 path_not_allowed
• 503 internal_secret_not_configured
• 503 authentik_admin_not_configured