Public Access — Unauthenticated Documentation Browsing

How unauthenticated users can view docs, projects, and files

Public Access — Unauthenticated Documentation Browsing

The docs system is designed so unauthenticated users can browse documentation without signing in. This supports public docs, shared links, and external readers.

Design Principle

Read operations are public. Write operations (admin, sync, preferences) require authentication.

Operation Auth required
View docs, projects, files, search No
Admin panel, View Sessions, config Yes (exec/dev/admin)
Preferences Yes (any authenticated user)

Public Backend Endpoints

All read endpoints use @Public() — no JWT required.

Content & Files

Endpoint Purpose
GET /docs-api/sync/files List all doc files (paginated)
GET /docs-api/sync/files/*path Get single file content by path
GET /docs-api/sync/manifest Full manifest (all file metadata)
GET /docs-api/sync/search?q= Search documentation

Projects & Config

Endpoint Purpose
GET /docs-api/sync/projects List all projects
GET /docs-api/sync/settings/:key Read setting by key
GET /docs-api/sync/settings Read all settings for namespace
GET /docs-api/admin/docs/folders-config Folders/projects config (structure)

View Sessions (Shareable Links)

Endpoint Purpose
GET /docs-api/sessions/:token Resolve view session token → allowedProjectIds

Analytics (Fire-and-Forget)

Endpoint Purpose
POST /docs-api/analytics/page-views Track page view
POST /docs-api/analytics/search-events Track search event

Frontend Access

Route Auth required
/ (select-project) No
/english/..., /es/... (docs content) No
/admin/* Yes (exec/dev/admin)
/preferences Yes (any authenticated user)

Unauthenticated users can:

  1. Land on the docs app
  2. Select a project from the switcher
  3. Browse all public documentation
  4. Use search

Modern Link-Based Sharing (View Sessions)

The primary way to share docs with specific projects is View Sessions:

  1. Admin (exec/dev/admin) goes to Admin → View Sessions
  2. Selects projects via checkboxes
  3. Creates shareable link → receives URL with ?v=TOKEN
  4. Recipient opens link (no auth) → sees only the selected projects

Flow:

Recipient opens https://docs.app.com/?v=abc123
    ↓
Frontend calls GET /docs-api/sessions/abc123
    ↓
Backend returns { allowedProjectIds: ["english/GoGrab-Space", ...] }
    ↓
Frontend filters availableProjects to those IDs only
    ↓
Recipient sees only allowed projects in switcher and content

Summary

Scenario Auth How
Public docs No Open docs URL → select project → browse
Restricted docs (specific projects) No Admin creates link → recipient opens ?v=TOKEN
Admin, config, View Sessions Yes Sign in as exec/dev/admin

All documentation read operations are public by design. Authentication is required only for administration and personal preferences.