Scott.Idem/OSIT-AE-API-FastAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(auth): consolidate and secure V3 authentication flow

Browse Source 
- Re-apply safe guest auth and passcode-to-JWT endpoint
- Consolidate AccountContext with token_payload and role flags
- Restore documentation for new guest flows and public read whitelists
- Fix 403 error in get_obj_li by allowing optional account context
This commit is contained in:
Scott Idem
2026-01-20 18:42:43 -05:00
parent d4e46a4a97
commit 43ac62b561
5 changed files with 392 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
documentation/V3_FRONTEND_API_GUIDE.md
View File

@@ -34,15 +34,25 @@ Once the API Key is validated, you must specify the context of your request.
* **Header:** `x-account-id: <account_id_random>`
2. **Administrative Bypass**: For authorized scripts needing global access.
* **Header:** `x-no-account-id: bypass`
3. **Authentication Requirement**: Standard `Authorization: Bearer <jwt>` is still required for user-level actions.
3. **Guest / Anonymous Access**: Provide a **Safe Guest JWT**.
* **Header:** `x-aether-api-key: <your_app_key>` (No Account Header)
* **Query Param:** `?jwt=<guest_token>`
* **Benefit:** Allows the backend to track cryptographically signed session state (e.g., site context) without granting full account access.
### C. The "Bootstrap Paradox" Exception (`site_domain`)
The **`site_domain` search** endpoint allows unauthenticated (**guest**) access so the frontend can resolve site configuration *before* login.
### C. Public Read Whitelist (Unauthenticated)
The V3 architecture allows unauthenticated (**guest**) access to specific objects, provided a valid API Key is present.
* **Endpoint:** `POST /v3/crud/site_domain/search`
* **Note:** Still requires a valid API Key.
* **Whitelisted Objects:** `site_domain`, `event`, `event_session`, `event_presentation`, `event_presenter`, `post`, `post_comment`, `archive`, `archive_content`, `hosted_file`.
* **Behavior:** Requests to these objects will succeed without a user-level JWT, but are strictly limited to **Read-Only** operations (GET/Search).
### D. Fail-Fast on Auth Failures (401/403)
### D. Passcode Authentication (Machine/Kiosk Logins)
For guest machines or specialized kiosks, use the dedicated passcode endpoint to receive a scoped JWT.
* **Endpoint:** `POST /api/authenticate_passcode`
* **Payload:** `{ "site_id": "<site_id_random>", "passcode": "<secret>" }`
* **Response:** Returns a JWT containing the site's `account_id` and resolved role flags (`super`, `manager`, `administrator`).
### E. Fail-Fast on Auth Failures (401/403)
The frontend implements a **Fail-Fast** policy for 401/403 errors. If the API returns these codes, the frontend **must not retry** automatically. It should stop and redirect the user or display an error.
---