FHIRfly
Dashboard

Dashboard Sessions

This page explains how the FHIRfly dashboard manages authentication sessions, including how tokens work, when sessions expire, and what to expect as a user.

How Sessions Work

When you sign in to the dashboard, the following happens:

  1. Magic link sent --- You enter your email and receive a 6-digit verification code
  2. Code verified --- The code is validated against the backend (expires after 15 minutes)
  3. Tokens issued --- The server issues two JWTs: an access token and a refresh token
  4. Cookies set --- Both tokens are stored as HttpOnly, Secure, SameSite=strict cookies

Your browser never sees the token values directly. All API calls from the dashboard go through a Backend-For-Frontend (BFF) proxy that injects the access token server-side.

Token Lifetimes

Token Lifetime Purpose
Access token 1 hour Authorizes dashboard API requests
Refresh token 30 days Obtains a new access token without re-authenticating
Magic link code 15 minutes One-time verification code sent via email

Session Refresh

The dashboard automatically keeps your session alive:

  • A background refresh runs every 30 minutes while the dashboard is open
  • When the access token is close to expiring, the BFF exchanges the refresh token for a fresh pair of tokens
  • Each refresh resets both the access token (1 hour) and refresh token (30 days) lifetimes

This means that if you use the dashboard regularly, your session can stay active indefinitely. There is currently no maximum session lifetime --- each successful refresh extends the session by another 30 days.

What Happens When a Session Expires

If you haven't visited the dashboard in over 30 days (so the refresh token expires), or if the refresh fails for any reason:

  1. The dashboard detects the expired session (via a 401 response)
  2. Your local auth state is cleared
  3. You see a "Your session has expired" message on the login page
  4. You can sign in again with a new magic link

The dashboard will never show empty data silently --- if your session expires, you are redirected to the login page with a clear message.

Security Details

All auth cookies use these security settings:

Setting Value Why
HttpOnly true Prevents JavaScript access (XSS protection)
Secure true (production) Cookies only sent over HTTPS
SameSite strict Prevents cross-site request forgery (CSRF)
Path / Available to all dashboard routes

Token Signing

Session tokens are signed with EdDSA (Ed25519) --- a modern, fast, and secure signing algorithm. Tokens include standard JWT claims (sub, iss, aud, exp, iat, jti).

CSRF Protection

In addition to SameSite=strict cookies, all dashboard API requests include an X-Requested-With: XMLHttpRequest header. The server rejects requests missing this header, providing defense-in-depth against CSRF attacks.

API Credential Sessions

If you are building an integration (not using the dashboard), session management works differently:

  • API Keys do not expire unless revoked --- see Authentication
  • OAuth2 tokens expire after 10 minutes and are re-obtained via the client credentials grant (no refresh tokens)

Next Steps