feat!: new api key system by ThibaudDauce · Pull Request #3636 · opendatateam/udata

ThibaudDauce · 2026-01-28T07:02:58Z

Replace the single User.apikey (JWS token stored on the user document) with a dedicated ApiToken collection supporting multiple tokens per user, HMAC-SHA256 hashed storage, revocation, expiration, and tracking
New API endpoints: POST /api/1/me/tokens/ (create), GET /api/1/me/tokens/ (list active), DELETE /api/1/me/tokens// (revoke) — the plaintext token is returned only once at creation
Remove the apikey field from the User model and the me_fields / apikey_fields API serializers, along with the old /me/apikey/ endpoint
Add an idempotent migration that hashes existing JWS apikeys with HMAC-SHA256 into the new api_token collection, preserving backward compatibility for existing consumers
Introduce API_TOKEN_SECRET and API_TOKEN_PREFIX settings for token hashing and secret-scanning tool integration

udata/core/user/api.py

udata/tests/api/__init__.py

udata/api/__init__.py

nicolaskempf57

Thanks for this PR ! I think we are ready on udata side, but it will require some changes in cdata and maybe other projects like front-kit if they also have an interface for the api key

ThibaudDauce · 2026-02-25T13:56:38Z

Thanks for this PR ! I think we are ready on udata side, but it will require some changes in cdata and maybe other projects like front-kit if they also have an interface for the api key

Done in datagouv/cdata#962

maudetes

🎉 I think it will be a very nice improvement for security and usability !

maudetes · 2026-02-26T09:40:09Z

docs/api-tokens.md

+
+Tokens are stored as HMAC-SHA256 hashes in a dedicated `api_token` MongoDB collection. Revoked tokens are kept for audit (soft-delete via `revoked_at`).
+
+## Previous system


I wouldn't document past system in this documentation?

maudetes · 2026-02-26T10:49:18Z

udata/auth/__init__.py

+    from udata.errors import ConfigError
    from udata.models import datastore

+    if not app.config.get("API_TOKEN_SECRET"):


Agreed it may be better to raise instead of leaving it by default. However, we should do the same for a list of settings for coherence?

for config in ["SECRET_KEY", "API_TOKEN_SECRET"]: ...

And I would add a API_TOKEN_SECRET in the different udata.cfg samples in docs.

maudetes · 2026-02-26T10:56:07Z

udata/core/user/api.py

+@me.route("/tokens/", endpoint="my_tokens")
+class TokenListAPI(API):


Can we use the wording api key instead of vague token?
In my understanding, other potential token usage would have distinct routes anyway?

maudetes · 2026-02-26T10:56:47Z

udata/core/user/api.py

+    @api.marshal_list_with(ApiToken.__read_fields__)
+    def get(self):
+        """List all my active API tokens"""
+        return list(ApiToken.objects(user=current_user._get_current_object(), revoked_at=None))


Could we do

Suggested change

return list(ApiToken.objects(user=current_user._get_current_object(), revoked_at=None))

return list(ApiToken.objects(user=current_user.id, revoked_at=None))

maudetes · 2026-02-26T12:29:33Z

udata/core/user/api.py

+    @api.marshal_list_with(ApiToken.__read_fields__)
+    def get(self):
+        """List all my active API tokens"""
+        return list(ApiToken.objects(user=current_user._get_current_object(), revoked_at=None))


Should it return expired tokens but not revoked?

maudetes · 2026-02-26T13:09:42Z

udata/core/user/models.py

        self.save()
+        from udata.core.user.api_tokens import ApiToken
+
+        ApiToken.objects(user=self, revoked_at=None).update(


I think we have a reverse rule on user = db.ReferenceField("User", required=True, reverse_delete_rule=db.CASCADE), thus the token will be deleted anyway?

maudetes · 2026-02-26T14:20:36Z

udata/api/__init__.py

-                if not login_user(user, False):
+                if not login_user(api_token.user, False):
                    self.abort(401, "Inactive user")
+                api_token.update_usage(request.headers.get("User-Agent"))


Don't we want to update usage in authenticate directly?

maudetes · 2026-02-26T14:48:34Z

udata/tests/api/test_auth_api.py

    def test_header_auth(self):
        """Should handle header API Key authentication"""
-        with self.api_user() as user:  # API Key auth
-            response = self.post(url_for("api.fake"), headers={"X-API-KEY": user.apikey})
+        with self.api_user():
+            response = self.post(url_for("api.fake"))


I'm confused, it doesn't test anything anymore?

maudetes · 2026-02-26T14:51:21Z

udata/core/user/api_tokens.py

+        token = cls.objects(token_hash=token_hash, revoked_at=None).first()
+        if token is None:
+            return None
+        if token.expires_at and token.expires_at < datetime.now(timezone.utc):


I think we have an issue of comparison between timezone naive and aware datetimes here?
I think we're missing a test for this.

maudetes · 2026-02-26T14:51:52Z

udata/core/user/api_tokens.py

+
+    @classmethod
+    def authenticate(cls, plaintext_token):
+        """Lookup a token by hashing the plaintext. Returns ApiToken or None."""


Don't we want to return appropriate error (revoked vs expired vs invalid?

ThibaudDauce added 7 commits January 28, 2026 08:02

feat: new api key system

277fe16

Use hmac instead of simple hash

9a13849

review tweaks

1f49450

fix wrong default scope

8968e62

improve doc

ad40ed0

improve doc

cb8f41e

switch datetime.utcnow() and simplify one function

63ca7f8

ThibaudDauce marked this pull request as ready for review February 5, 2026 12:41

ThibaudDauce requested review from maudetes and nicolaskempf57 and removed request for maudetes February 5, 2026 12:41

nicolaskempf57 reviewed Feb 19, 2026

View reviewed changes

udata/core/user/api.py Outdated Show resolved Hide resolved

nicolaskempf57 reviewed Feb 19, 2026

View reviewed changes

udata/tests/api/__init__.py Outdated Show resolved Hide resolved

nicolaskempf57 reviewed Feb 19, 2026

View reviewed changes

udata/api/__init__.py Show resolved Hide resolved

nicolaskempf57 reviewed Feb 19, 2026

View reviewed changes

ThibaudDauce added 2 commits February 25, 2026 14:39

Merge branch 'main' into new_api_key_system

0d6ce03

add prefix into token preview

ed62f80

ThibaudDauce mentioned this pull request Feb 25, 2026

feat: new API keys datagouv/cdata#962

Open

ThibaudDauce added 2 commits February 25, 2026 14:58

fix review

ee8dcb3

fix small problem in migration

a0b0abc

maudetes reviewed Feb 26, 2026

View reviewed changes


		Tokens are stored as HMAC-SHA256 hashes in a dedicated `api_token` MongoDB collection. Revoked tokens are kept for audit (soft-delete via `revoked_at`).

		## Previous system

		@me.route("/tokens/", endpoint="my_tokens")
		class TokenListAPI(API):

	return list(ApiToken.objects(user=current_user._get_current_object(), revoked_at=None))
	return list(ApiToken.objects(user=current_user.id, revoked_at=None))

Conversation

ThibaudDauce commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nicolaskempf57 left a comment

Choose a reason for hiding this comment

Uh oh!

ThibaudDauce commented Feb 25, 2026

Uh oh!

maudetes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ThibaudDauce commented Jan 28, 2026 •

edited

Loading