FiloraFS-Prov2
FiloraFS-Pro API reference
Reference FiloraFS-Pro v2 authentication, owner-scoped file, user, temporary-access, and admin storage endpoints.
Updated
Browser API workbench
Run FiloraFS-Pro and open http://localhost:8080/api-test. Register and log in before exercising owner-scoped file operations; use a ROLE_ADMIN account for storage management.
Authentication endpoints
| Method | Path | Access | Purpose |
|---|---|---|---|
| POST | /api/auth/register | Public | Create a ROLE_USER account |
| POST | /api/auth/login | Public | Create a session and return JWT/refresh credentials |
| POST | /api/auth/refresh | Public | Rotate the opaque refresh credential |
| POST | /api/auth/logout | Bearer JWT | Revoke the owned current session |
User endpoints
| Method | Path | Access | Purpose |
|---|---|---|---|
| GET | /api/users/me | Bearer JWT | Return the current user's id, username, email, and roles |
| GET | /api/users | ROLE_ADMIN | Return pageable user summaries |
Owner-scoped file endpoints
| Method | Path | Access | Purpose |
|---|---|---|---|
| POST | /file | Bearer JWT | Upload to the active provider as the authenticated owner |
| GET | /file/list | Bearer JWT | List owned files; ROLE_ADMIN sees all |
| GET | /file/info/{id} | Owner / ROLE_ADMIN | Read persisted metadata |
| GET | /file/stream/{id} | Owner / ROLE_ADMIN | Stream inline |
| GET | /file/download/{id} | Owner / ROLE_ADMIN | Download as an attachment |
| DELETE | /file/{id} | Owner / ROLE_ADMIN | Delete object, thumbnail, and metadata |
| GET | /file/thumbnail/{id} | Owner / ROLE_ADMIN | Return JPEG thumbnail or fallback SVG |
| POST | /file/generate-pre-signed-url | Owner / ROLE_ADMIN | Create temporary access up to 604800 seconds |
| GET | /file/presigned/{token} | Public valid token | Resolve unexpired application-token access |
POST/fileBearer JWT
Upload one validated multipart file through the active LOCAL or S3-compatible provider and persist mandatory owner/provider metadata.
Headers
Authorization: Bearer <access-token>Content-Type: multipart/form-data
Parameters
- file — required multipart file part
Relevant errors
- 401 when the JWT is missing or invalid.
- 400 or 413 when size, extension, MIME type, or signature validation fails.
- 503 when the active provider is unavailable; no silent fallback occurs.
cURL
curl -X POST http://localhost:8080/file \
-H "Authorization: Bearer <access-token>" \
-F "file=@architecture.pdf"GET/file/listBearer JWT
Return the caller's persisted file metadata. ROLE_ADMIN returns metadata across users.
Headers
Authorization: Bearer <access-token>
Relevant errors
- 401 when the JWT is missing or invalid.
POST/file/generate-pre-signed-urlOwner / ROLE_ADMIN
Create expiring access for a LOCAL or S3-backed file.
Headers
Authorization: Bearer <access-token>Content-Type: application/json
Parameters
- id — positive file ID
- expiresInSeconds — 1 to 604800
Relevant errors
- 401 for a missing or invalid JWT.
- 403 for a different user's file.
- 404 when the file does not exist.
Storage administration endpoints
| Method | Path | Access | Purpose |
|---|---|---|---|
| GET | /api/storage/status | ROLE_ADMIN | Return active provider, configuration state, and availability |
| GET | /api/storage/config | ROLE_ADMIN | Return sanitized persisted configuration and credential-presence flags |
| PUT | /api/storage/config/local | ROLE_ADMIN | Persist a contained relative LOCAL path without activating it |
| PUT | /api/storage/config/s3 | ROLE_ADMIN | Persist encrypted S3-compatible settings without activating S3 |
| POST | /api/storage/test/local | ROLE_ADMIN | Probe configured LOCAL writability |
| POST | /api/storage/test/s3 | ROLE_ADMIN | Probe configured S3-compatible bucket access |
| PUT | /api/storage/provider | ROLE_ADMIN | Test and explicitly activate LOCAL or S3 |