Skip to content

Use UUIDv7 for JTI claim on Python 3.13+#979

Open
jesustorres-code wants to merge 2 commits into
jazzband:masterfrom
jesustorres-code:feat/uuidv7-jti
Open

Use UUIDv7 for JTI claim on Python 3.13+#979
jesustorres-code wants to merge 2 commits into
jazzband:masterfrom
jesustorres-code:feat/uuidv7-jti

Conversation

@jesustorres-code
Copy link
Copy Markdown

Closes #943

What

Replace uuid4 with uuid7 for JTI generation on Python 3.13+, falling back to uuid4 on older versions.

try:
    from uuid import uuid7 as _uuid_for_jti  # Python 3.13+
except ImportError:
    from uuid import uuid4 as _uuid_for_jti

Why

UUIDv7 is time-ordered (monotonically increasing), which makes it significantly more efficient as a b-tree index key in the OutstandingToken table used for blacklisting. UUIDv4's random distribution causes index fragmentation and write amplification at scale; UUIDv7 inserts append near the end of the index, reducing page splits.

Python 3.13 added uuid.uuid7() to the standard library (PEP 769). Older supported versions (3.10–3.12) fall back to uuid4, preserving existing behavior.

Changes

  • rest_framework_simplejwt/tokens.py: conditional import; set_jti() uses _uuid_for_jti().hex
  • tests/test_tokens.py: added format assertion (32-char hex string) to test_set_jti

No migration needed — the JTI column type and length are unchanged (hex string, 32 chars).

Ubuntu and others added 2 commits May 20, 2026 20:05
UUIDv7 is time-ordered, which makes it more efficient as a b-tree index
key in databases used for token blacklisting. Falls back to uuid4 on
Python < 3.13 where uuid7 is not available in the standard library.

Closes jazzband#943
Copy link
Copy Markdown
Member

@Andrew-Chen-Wang Andrew-Chen-Wang left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks!

Comment on lines +4 to +7
try:
from uuid import uuid7 as _uuid_for_jti # Python 3.13+
except ImportError:
from uuid import uuid4 as _uuid_for_jti # type: ignore[assignment]
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
try:
from uuid import uuid7 as _uuid_for_jti # Python 3.13+
except ImportError:
from uuid import uuid4 as _uuid_for_jti # type: ignore[assignment]
try:
from uuid import uuid7 as _uuid_for_jti # Python 3.13+
except ImportError:
from uuid import uuid4 as _uuid_for_jti # type: ignore[assignment]
uuid = _uuid_for_jti

so that users can override it

@lets-build-an-ocean
Copy link
Copy Markdown

Hey @jesustorres-code, great work on this — UUIDv7 for JTI is a solid improvement especially for blacklisting at scale.

Are you planning to address @Andrew-Chen-Wang's suggestion of exposing uuid = _uuid_for_jti for user override? If you're busy or don't have time, I'm happy to pick it up and carry this across the finish line with full credit to you.

I'm actively looking to contribute to open source projects and this would be a great place to start!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Change JTI to use UUIDv7

3 participants