Authentication

The admin shell authenticates with a single bearer token. A successful login mints a short-lived in-memory session, carried by an HttpOnly cookie. The token can be rotated from within the UI, and a startup warning nudges you away from weak secrets.

Bearer token

Sign in at GET /_admin/login, which renders an empty login card where you enter the admin token. The submitted token is compared in constant time against the configured value. A failed token re-renders the form with the inline error Token does not match. Try again. and consumes a rate-limit permit.

Login is rate-limited to 10 failed attempts per minute, using a token-bucket limiter shared with the POST /_admin/reload endpoint, so brute-forcing across both surfaces is bounded. When the limit is exhausted the endpoint responds 429 with the same error shape.

On a successful login the server mints a 32-byte random session ID, stores it in an in-memory session store, and returns it as the accentcms_admin cookie. The cookie is:

  • HttpOnly
  • SameSite=Lax
  • scoped to Path=/_admin/
  • Secure in production mode only (--production); the Secure attribute is omitted in dev mode so the cookie works over plain HTTP on localhost
  • valid for 8 hours (the session TTL)

Sessions live in memory only and do not persist across server restarts. A background sweep task prunes expired sessions every 60 seconds.

GET /_admin and GET /_admin/ redirect an authenticated session to /_admin/dashboard, and otherwise to /_admin/login. POST /_admin/logout clears the session cookie, drops the in-process session, and redirects to /_admin/login.

Token rotation

Open Settings → Rotate token (POST /_admin/settings/rotate-token). On confirm the server:

  • mints a fresh 32-byte token (written as hex),
  • writes it to a .env.admin file next to config.yaml,
  • clears every active session, and
  • redirects you back to the login screen.

Persisting in .env.admin rather than rewriting config.yaml keeps the secret out of any file you might commit to source control. The rotation timestamp is logged in ISO 8601 form, and the Settings screen surfaces the last rotation time.

Minimum token length

There is no hard length enforcement at config-parse time, but a startup warning is logged when the token is shorter than 16 characters in production. The recommended minimum is 32 bytes of entropy.