Authentication

MikroPlan uses MikroAuth for passwordless magic-link sign-in when API auth is enabled.

Auth is disabled by default. Local mode does not need accounts or sign-in.

When auth is disabled, the API reports local mode through /config.json and magic-link requests return a local-mode message without sending email.

Access Model

When auth is enabled, MikroPlan uses a single collaborator role. Anyone whose email matches auth.allowedEmails or auth.allowedDomains can sign in and read or write the whole shared workspace.

There are no per-board roles, private boards, or read-only users in the current collaboration API.

Enable Auth

Copy the example config:

cp mikroplan.config.json.example mikroplan.config.json

The server reads this file through MikroConf, with environment variables and CLI flags available for deployment-specific overrides.

Set auth.enabled to true, replace auth.jwtSecret with a secret of at least 32 characters, and configure SMTP under email.

{
  "auth": {
    "enabled": true,
    "allowedEmails": ["[email protected]"],
    "allowedDomains": ["example.com"],
    "jwtSecret": "replace-with-a-long-secret",
    "magicLinkExpirySeconds": 900,
    "jwtExpirySeconds": 3600,
    "maxActiveSessions": 3,
    "refreshTokenExpirySeconds": 604800
  },
  "email": {
    "emailSubject": "Sign in to MikroPlan",
    "host": "smtp.example.com",
    "user": "[email protected]",
    "password": "smtp-password",
    "port": 465,
    "secure": true,
    "maxRetries": 2,
    "debug": false
  }
}

Keep mikroplan.config.json local. It can contain SMTP credentials and auth secrets.

Leave either allowedEmails or allowedDomains empty if you do not need that matching mode, but at least one must contain a value when auth is enabled.

Startup Validation

When auth is enabled, MikroPlan refuses to start unless:

• an email or domain allowlist is configured
• auth.jwtSecret is changed and long enough
• SMTP host, user, password, subject, and port are configured
• auth expiry settings and max sessions are valid

This keeps test-mode email from accidentally becoming production auth.

Environment Overrides

Use environment variables for deployment secrets:

• MIKROPLAN_AUTH_ENABLED
• MIKROPLAN_AUTH_ALLOWED_EMAILS
• MIKROPLAN_AUTH_ALLOWED_DOMAINS
• MIKROPLAN_AUTH_JWT_SECRET
• MIKROPLAN_AUTH_MAGIC_LINK_EXPIRY
• MIKROPLAN_AUTH_JWT_EXPIRY
• MIKROPLAN_AUTH_REFRESH_EXPIRY
• MIKROPLAN_AUTH_MAX_SESSIONS
• MIKROPLAN_EMAIL_SUBJECT
• MIKROPLAN_EMAIL_HOST
• MIKROPLAN_EMAIL_USER
• MIKROPLAN_EMAIL_PASSWORD
• MIKROPLAN_EMAIL_PORT
• MIKROPLAN_EMAIL_SECURE

Sessions

MikroAuth magic-link and session state is stored in the same SQLite database as the workspace. Server restarts do not invalidate active sessions.

After verification, the API sets an HttpOnly mikroplan_access_token cookie. The browser app uses that cookie for workspace requests and Server-Sent Events, so tokens are not stored in local storage or placed in query strings.

Use /api/auth/me to check whether the current browser has a valid session.

Use /api/auth/logout to clear the cookie.