Refresh tokens

[nhoening]

We support only access tokens, but refresh tokens provide higher security compliance, as a complete re-auth is not needed as often.

Flask-Security(-Too) supports them in an upcoming version (5.9), so from that point on, we should support them.

Here is an initial plan:

1. Wait for Flask-Security-Too >=5.9.0. (documentation is already online, see the latest version)

2. Prototype on a branch:

   • add the refresh-tracker SQLAlchemy model/table/migration;
   • pass the refresh tracker model into SQLAlchemySessionUserDatastore;
   • enable SECURITY_REFRESH_TOKEN;
   • decide whether refresh tokens are returned as secure HTTP-only cookies or JSON. For FlexMeasures API clients, JSON may be more practical, but cookies are safer for browser flows.

3. Keep /api/requestAuthToken backward-compatible. Existing clients expect:

   {
     "auth_token": "...",
     "user_id": 123
   }
   

   If refresh tokens are added, add fields without renaming auth_token.

4. Add a separate refresh endpoint, probably something like POST /api/refreshAuthToken or expose/wrap Flask-Security’s /refresh-token, returning a new auth_token and rotated refresh token.

5. Add tests for:

   • initial access + refresh token issuance;
   • refreshing without resending password;
   • refresh-token rotation;
   • reuse of an old refresh token being rejected;
   • password reset / user deactivation revoking refresh access.

6. Update docs and UI wording. Several docs already talk about access tokens “requiring refresh”, but there is no actual refresh-token flow documented yet.