Skip to main content

​
Login

Users log in at admin.woku.app/login with their email (or username) + password. The password is compared against a bcrypt hash; the plaintext password is never stored or transmitted beyond the form itself. A successful login generates:
  • An access token (signed JWT) that the client attaches as Authorization: Bearer <token> on every request.
  • An opaque refresh token (32 random bytes, single-use) valid for 30 days.
  • A server-side persisted Session that binds the token to a user and allows it to be revoked or expired.

​
Idle timeout

Every authenticated request refreshes the session’s lastActivity field (debounced every 60 seconds so the database is not overloaded). If the session stays inactive for longer than the configured time, it closes automatically: the next request receives 401 Unauthorized and the user must log in again.
  • Default: 30 minutes of inactivity leads to closure.
  • Per-session override: optional, via the session’s idleTimeoutMin field.
  • Global override: the SESSION_IDLE_TIMEOUT_MIN environment variable.
Idle closure also persists isClosed: true on the session, so an attacker with the stolen token cannot use it either.

​
Refresh tokens (single-use rotation)

When the client wants to extend the session without asking the user to enter their credentials again, it sends its current refresh token to the authentication service. The server:
  1. Verifies that the refresh token exists, is not closed, and is not expired.
  2. Generates a new pair (access + refresh) and invalidates the old one atomically in the same Session row.
  3. Returns the new pair.
If the refresh token is unknown, closed, or already expired, the response is 401 Unauthorized and the user must log in again.

​
Logout

On logout, the session is marked as closed (isClosed: true). From that point on, no request with that access token or its refresh token works.

​
Guarantees

  • Tokens never appear in the URL: they only travel in the header or body, and TLS protects them in transit (see Headers and CSP for HSTS).
  • Immediate revocation: the admin can revoke any session from the backoffice endpoint; the next request from the revoked token fails.
  • Compatibility: the access-token-only flow still works for clients that do not implement refresh (rotation is opt-in).