Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/noelzappy/vaulx/llms.txt

Use this file to discover all available pages before exploring further.

Vaulx uses server-side session cookies — not API keys or JWTs. When you POST valid credentials to /auth/login, the server creates a session record in PostgreSQL and sends a vaulx-session cookie back to the client. Every subsequent request to a protected route must include that cookie. There is no token-based alternative; if the cookie is absent or the session is invalid, the server redirects you to /auth/login.

​
Login Flow

1

Render the login page

Send a GET /auth/login request. The server returns a full HTML login page.
curl http://localhost:8080/auth/login
2

Submit credentials

POST your credentials as a URL-encoded form body. On success, the server sets the vaulx-session cookie and issues a 302 Found redirect to /files.
curl -c cookies.txt -X POST http://localhost:8080/auth/login \
  -d 'email=admin@example.com&password=yourpassword'
​
email
string
required
The email address associated with the user account.
​
password
string
required
The account password. Verified against a bcrypt hash stored in the database.
The Content-Type must be application/x-www-form-urlencoded (the default for HTML forms and curl -d flags). Sending JSON to this endpoint will not work.
3

Use the session cookie on subsequent requests

Pass the saved cookie jar on every authenticated request. The cookie is validated server-side on each call.
curl -b cookies.txt http://localhost:8080/files
After a successful login, the server writes a cookie with the following attributes — sourced directly from sessionStore.Options in cmd/server/main.go:
AttributeValueNotes
Namevaulx-sessionFixed cookie name used by the gorilla/sessions store
Path/Cookie is sent on all paths
MaxAge604800 seconds (7 days)Session expires one week after login
HttpOnlytrueNot accessible via JavaScript document.cookie
SameSiteLaxSent on top-level navigations; protects against most CSRF
SecuretrueOnly sent over HTTPS connections
The Secure flag means the login cookie will not be set over plain HTTP in production. You must configure TLS directly on the Vaulx server or place it behind a TLS-terminating reverse proxy (e.g. Caddy, Nginx, or a cloud load balancer) before attempting to log in from a non-localhost client.
Session data is stored in PostgreSQL via pgstore — the cookie itself contains only a session ID, not any user data. The store runs a background cleanup goroutine every 5 minutes to purge expired sessions from the database.

​
Session Values

Once authenticated, the following values are written into the server-side session record and loaded into the request context on every protected request:
KeyTypeDescription
user_idstring (UUID)Unique identifier of the authenticated user
rolestringUser’s role — admin or editor
emailstringUser’s email address
namestringUser’s display name
These values are surfaced to handlers as a UserContext struct (defined in internal/auth/context.go): 
type UserContext struct {
    ID    string // UUID string of the authenticated user
    Email string
    Name  string
    Role  string
}
Handlers retrieve it with auth.GetCurrentUser(r.Context()).

​
Access Control

Two helper functions in internal/auth/acl.go govern what an authenticated user may do: 
// CanAccess reports whether user may access a resource owned by ownerID.
// Phase 1 stub: admin bypasses all checks; others require ownership.
func CanAccess(user UserContext, ownerID string) bool {
    if user.Role == "admin" {
        return true
    }
    return user.ID == ownerID
}

// CanEdit reports whether the user may create or modify resources.
func CanEdit(user UserContext) bool {
    return user.Role == "admin" || user.Role == "editor"
}
  • admin — full access to all resources and all admin routes under /admin/.
  • editor — can create and modify resources they own.
  • Any other role — read-only access to owned resources.

​
Logout

Sending POST /auth/logout sets the session’s MaxAge to -1, which instructs the browser to immediately expire the cookie, and then redirects to /auth/login. 
curl -b cookies.txt -X POST http://localhost:8080/auth/logout

​
curl Walkthrough

The following end-to-end example logs in, lists files, and then logs out: 
# 1. Log in and save the session cookie to a local file
curl -c cookies.txt -X POST http://localhost:8080/auth/login \
  -d 'email=admin@example.com&password=yourpassword'

# 2. Use the saved cookie on subsequent requests
curl -b cookies.txt http://localhost:8080/files

# 3. Call a JSON API endpoint
curl -b cookies.txt http://localhost:8080/api/folders \
  -H 'Accept: application/json'

# 4. Log out
curl -b cookies.txt -c cookies.txt -X POST http://localhost:8080/auth/logout
The -c cookies.txt flag on the logout call tells curl to update the saved cookie file so the expired cookie is written back to disk, preventing it from being inadvertently reused.

​
Error Responses

ScenarioHTTP statusBehaviour
Wrong email or password401 UnauthorizedRe-renders the login page with the message “Invalid email or password”
Protected route accessed without a session cookie302 FoundRedirects to /auth/login
Session cookie present but session record is new/invalid302 FoundRedirects to /auth/login
Authenticated but insufficient role for an admin route403 ForbiddenReturns a 403 HTML error page
​
error message (login)
string
On a 401 response the login page is re-rendered with an inline error message: "Invalid email or password". No JSON error body is returned.

Build docs developers (and LLMs) love

Get started for freeTalk to us