[nhoening]

Description

Closes #2229

The

• Clients can opt in to get refresh tokens with the eisting ndpoint for auth token access
• Clients can rotate tokens
• Clients can revoke a token family.
• New fields use kebab-case; the existing auth_token, user_id, and access-token lifetime remain compatible.
• Added changelog item in documentation/changelog.rst

Look & Feel

Check the new documentation and API endpoints.

How to test

Here is a bash script:

uv run --no-project --with requests python - <<'PY'
import getpass
import requests

base = "http://localhost:5000"
email = input("Email: ")
password = getpass.getpass("Password: ")

# Log in and opt in to refresh tokens.
response = requests.post(
    f"{base}/api/requestAuthToken",
    json={
        "email": email,
        "password": password,
        "include-refresh-token": True,
    },
    timeout=30,
)
response.raise_for_status()
first = response.json()
print("Login succeeded; access token lifetime:", first["expires-in"], "seconds")

# Exchange the refresh token.
response = requests.post(
    f"{base}/api/refreshAuthToken",
    json={"refresh-token": first["refresh-token"]},
    timeout=30,
)
response.raise_for_status()
second = response.json()
assert second["refresh-token"] != first["refresh-token"]
print("Refresh succeeded; a replacement refresh token was issued.")

# Use the new access token for an ordinary API request.
response = requests.get(
    f"{base}/api/v3_0/users/{second['user_id']}",
    headers={"Authorization": second["auth_token"]},
    timeout=30,
)
response.raise_for_status()
print("The new access token works.")

# Reuse of the old refresh token must fail and revoke the family.
response = requests.post(
    f"{base}/api/refreshAuthToken",
    json={"refresh-token": first["refresh-token"]},
    timeout=30,
)
assert response.status_code == 401, response.text
response = requests.post(
    f"{base}/api/refreshAuthToken",
    json={"refresh-token": second["refresh-token"]},
    timeout=30,
)
assert response.status_code == 401, response.text
print("Replay was rejected and the refresh-token family was revoked.")
PY

Future work

The client needs to support this, as well.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #35758406 | 📁 Comparing df93c49 against latest (055d54d)

  🔍 Preview build  

14 files changed · + 4 added · ± 10 modified

+ Added

• _autosummary/flexmeasures.api.refresh_tokens.html
• _autosummary/flexmeasures.auth.datastore.html
• _autosummary/flexmeasures.auth.tokens.html
• _autosummary/flexmeasures.data.models.refresh_tokens.html

± Modified

• changelog.html
• genindex.html
• http-routingtable.html
• py-modindex.html
• _autosummary/flexmeasures.api.html
• _autosummary/flexmeasures.auth.html
• _autosummary/flexmeasures.data.models.html
• api/introduction.html
• api/v3_0.html
• concepts/security_auth.html