Authentication API
Password-based authentication endpoints for initial setup and session management.
Overview
Media Viewer uses session-based authentication with an HTTP-only cookie. After a successful login, the server sets a cookie that must be included in later requests.
Session Cookie
- Name:
media_viewer_session HttpOnly:trueSameSite:Strict- Expiration: configurable server-side session duration
- Behavior: sliding expiration for authenticated API activity
Initial Setup
Create the first password when the instance has no users yet.
Request
Notes
- Only available before initial setup is complete.
- Passwords must be between 6 and 72 characters.
Response
Check Authentication State
Return both session state and setup state.
Response
Authenticated:
Not authenticated:
Setup required:
Login
Authenticate with the configured password and receive a session cookie.
Request
Response
The response also sets a Set-Cookie header for media_viewer_session.
Logout
Destroy the current session and clear the cookie.
Response
Change Password
Update the password for the instance.
Request
Notes
newPasswordmust be between 6 and 72 characters.- Invalid current password returns
401 Unauthorized.
Response
Keep Session Alive
Refresh the current session explicitly.
Response
Error Behavior
Authentication endpoints commonly return plain-text 400 and 401 responses for invalid request bodies, short passwords, missing sessions, or invalid credentials.
For WebAuthn-specific endpoints, see webauthn.md.