Usage Guide

Everything you need to understand what SecShare is, what it's for, and how to use it — from the web app or directly against the API.

Overview

SecShare is a self-hosted, authenticated file-sharing service. It gives each user a private space to store and retrieve files through a simple REST API and a lightweight web interface.

The core idea is ownership isolation: when you upload a file it belongs to your account only. No other user can list, download, or delete it. Every request that touches files must carry a valid access token, so files are never exposed anonymously.

Machine-readable version. A JSON description of the API is always available at GET /api/info — useful for scripts, integrations, and quick reference.

Who it's for

Individuals who want a private, no-frills place to keep documents accessible from anywhere.
Small teams that need each member to hold their own set of files behind a login.
Developers who want a clean REST backend to build on, or to use as a reference for JWT-secured file handling.
Learning & security testing, where a compact, self-contained upload/download service is useful to study.

Getting started

Open the home page and choose Create account.
Enter your email and a password of at least 8 characters, then submit.
Switch to Sign in and log in with the same credentials.
You'll land on your dashboard, where you can upload files and see your storage usage.

The web app keeps you signed in across page reloads by storing your access token in the browser. Use Sign out to clear it.

Authentication

SecShare uses JWT bearer tokens. You obtain a token by logging in, then attach it to every protected request.

1. Register

curl -X POST https://your-host/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"supersecret"}'

2. Log in and capture the token

curl -X POST https://your-host/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"supersecret"}'

# → { "accessToken": "eyJhbGciOi..." }

3. Call a protected endpoint

curl https://your-host/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOi..."

Token lifetime. Access tokens expire after 60 minutes. When a token expires the API returns 401 Unauthorized; simply log in again to get a new one. The web app signs you out automatically when this happens.

Working with files

Upload

Send the file as multipart form data under the field name file:

curl -X POST https://your-host/api/files/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/report.pdf"

The response contains the stored file's id, name, size, content type, and creation time.

List your files

curl https://your-host/api/files \
  -H "Authorization: Bearer $TOKEN"

Download

curl https://your-host/api/files/<id> \
  -H "Authorization: Bearer $TOKEN" -O -J

Delete

curl -X DELETE https://your-host/api/files/<id> \
  -H "Authorization: Bearer $TOKEN"

Deletion is permanent and only works on files you own; requesting someone else's file returns 403 Forbidden.

API reference

Method	Path	Auth	Description
POST	`/api/auth/register`	Public	Create a new account.
POST	`/api/auth/login`	Public	Exchange credentials for a JWT.
GET	`/api/auth/me`	🔒 Bearer	Current user's profile.
GET	`/api/files`	🔒 Bearer	List your files.
POST	`/api/files/upload`	🔒 Bearer	Upload a file.
GET	`/api/files/{id}`	🔒 Bearer	Download a file you own.
DELETE	`/api/files/{id}`	🔒 Bearer	Delete a file you own.
GET	`/api/files/all`	🔒 Admin	List all files (ADMIN only).
GET	`/api/info`	Public	Machine-readable usage guide.
GET	`/health`	Public	Liveness check.

Limits & rules

Maximum file size: 50 MB per file.
Allowed types: pdf, png, jpg, jpeg, txt, doc, docx, xlsx, zip.
Password: minimum 8 characters at registration.
Isolation: you can only access files owned by your account.

FAQ

Can other people see my files?

No. Files are scoped to the account that uploaded them. Only an administrator role can list files across all users.

What happens when my token expires?

Protected requests start returning 401 Unauthorized. Log in again to obtain a fresh token; the web app does this transition for you by signing you out.

Why was my upload rejected?

The most common reasons are an unsupported file extension or a file larger than 50 MB. The API responds with 400 Bad Request or 413 Payload Too Large and a short message explaining which rule was violated.

Is there a programmatic list of endpoints?

Yes — call GET /api/info for a JSON summary of the service, its limits, and every endpoint.