feat(api-v3): implement temporary ?key= access pattern and update guide

- Added ?key= query param support for unauthenticated direct downloads.
- Fixed site table column bug (auth_key -> access_key).
- Updated GUIDE__V3_FRONTEND_API.md with temporary auth documentation.
- Ensured valid keys bypass the 403 Machine Auth requirement.
This commit is contained in:
Scott Idem
2026-02-03 18:03:03 -05:00
parent e29ff23f32
commit cc5af1c2e2
2 changed files with 28 additions and 6 deletions

View File

@@ -88,12 +88,21 @@ V3 uses specialized **"Action"** routes for binary operations to separate proces
### B. Download & Streaming Action
**Path**: `GET /v3/action/hosted_file/{id}/download`
**Query Parameters:**
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `key` | String | **Temporary V3.0 Auth:** Pass any valid `account_id_random` to bypass headers. |
| `site_key` | String | Bypass headers via `access_key` from the `site` table. |
| `filename` | String | Override the response filename. |
**Features:**
- **ID Vision:** Automatically resolves `{id}` if it belongs to a container object (e.g., `event_file`) instead of a direct `hosted_file`.
- **Streaming:** Supports standard `Range` headers for large files and video seeking.
- **Auth Bypass:** Use `?site_key=<auth_key>` to download without an API Key header or JWT (useful for public kiosks).
- **Testing:** Supports `delay_ms` query parameter.
> [!WARNING]
> **TEMPORARY SOLUTION (V3.0):** The `?key=` and `?site_key=` unauthenticated access patterns are intended to unblock the frontend for inline images and direct links where custom headers are not possible. This will be replaced by a standardized Signed URL or Read-Token system in **Version 3.1**. Please do not rely on this pattern for long-term security architecture.
### C. Hash-Based Download (Content-Addressable)
**Path**: `GET /v3/action/hosted_file/hash/{sha256}/download`