{"id":35387528,"url":"https://github.com/ixunio/superjwt","last_synced_at":"2026-01-29T02:03:20.595Z","repository":{"id":328653282,"uuid":"1107658863","full_name":"ixunio/superjwt","owner":"ixunio","description":"A modern implementation of JSON Web Token (JWT) for Python. With powerful Pydantic validation features.","archived":false,"fork":false,"pushed_at":"2026-01-13T18:45:12.000Z","size":989,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T19:44:40.680Z","etag":null,"topics":["jwt","pydantic","python","security"],"latest_commit_sha":null,"homepage":"https://ixunio.github.io/superjwt/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ixunio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-01T12:47:30.000Z","updated_at":"2026-01-13T18:44:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ixunio/superjwt","commit_stats":null,"previous_names":["ixunio/superjwt"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ixunio/superjwt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixunio%2Fsuperjwt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixunio%2Fsuperjwt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixunio%2Fsuperjwt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixunio%2Fsuperjwt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ixunio","download_url":"https://codeload.github.com/ixunio/superjwt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ixunio%2Fsuperjwt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jwt","pydantic","python","security"],"created_at":"2026-01-02T07:30:43.281Z","updated_at":"2026-01-29T02:03:20.588Z","avatar_url":"https://github.com/ixunio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cpicture\u003e\n\u003cimg alt=\"SuperJWT full logo\" src=https://raw.githubusercontent.com/ixunio/superjwt/main/docs/assets/logo-full-superjwt.png\u003e\n\u003c/picture\u003e\n\u003cbr /\u003e\n\u003cem\u003e\nA modern implementation of JSON Web Token (JWT) for Python.\n\u003cbr /\u003e\nWith powerful Pydantic validation features.\n\u003c/em\u003e\n\u003c/p\u003e\n\n\u003ca href=\"https://github.com/ixunio/superjwt/actions?query=event%3Apush+workflow%3ACI+branch%3Amain++\"\u003e\u003cimg alt=\"GitHub Actions workflow status on main branch\" src=\"https://img.shields.io/github/actions/workflow/status/ixunio/superjwt/ci.yml?branch=main\u0026logo=github-actions\u0026logoColor=white\u0026label=CI\"\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/github/ixunio/superjwt\"\u003e\u003cimg src=\"https://codecov.io/github/ixunio/superjwt/graph/badge.svg?token=RF0O8W5LKG\"/\u003e\u003c/a\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://pypi.org/project/superjwt/#history\"\u003e\u003cimg alt=\"PyPI - Version\" src=\"https://img.shields.io/pypi/v/superjwt?color=blue\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/superjwt/#history\"\u003e\u003cimg alt=\"Supported Python versions\" src=\"https://img.shields.io/pypi/pyversions/superjwt.svg?logo=python\u0026logoColor=white\"\u003e\u003c/a\u003e\n\n\u003cbr /\u003e\n\u003cbr /\u003e\n\n🔗 \u003ca href=\"https://ixunio.github.io/superjwt/latest/\"\u003e\u003cstrong\u003eDocumentation\u003c/a\u003e\u003c/strong\u003e\n\u003cbr\u003e\n🔗 \u003ca href=\"https://jwt.how\"\u003e\u003cstrong\u003eJWT Playground\u003c/strong\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n## Overview \u0026 Installation\n\nSuperJWT is a minimalist JWT library for Python 3.10+ that combines the simplicity of JWT encoding/decoding with the power of [Pydantic](https://docs.pydantic.dev/latest/) validation. It supports JWS (JSON Web Signature) format, HMAC and asymmetric algorithms (RSA, ECDSA, EdDSA). SuperJWT includes advanced features like enhanced time integrity checks, compact token inspection, custom timestamp serialization, detached payload mode, time spoofing and more.\n\n**Key Features:**\n\n- 🔐 **Secure by default** - JWS signature algorithm required.\n- 🪶 **Minimalist** - Clean, modern code with minimal dependencies.\n- ✔️ **JWT validation** - Easy claims validation with Pydantic models.\n- 🏷️ **Type hints** - IDE autocompletion with your JWT claims or JOSE headers.\n\n**Install via pip:**\n\n```bash\npip install superjwt\n```\n\n---\n\n## Usage\n\nSuperJWT makes it easy to encode and decode JWT tokens with automatic validation and serialization. Here are the fundamental operations:\n\n### Basic Usage 🐣\n\nEncode manually your claims from a `dict`. During decoding, validate your JWT content against a standard JWT claims Pydantic model.\n\n```python\nfrom superjwt import Alg, JWTClaims, encode, decode\n\nsecret_key = \"your-secret-key-of-len-32-bytes!\"\n\ncompact: bytes = encode({\"iss\": \"my-app\", \"sub\": \"John Doe\"}, secret_key, Alg.HS256)\nprint(compact)\n#\u003e b'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\n#   .eyJpc3MiOiJteS1hcHAiLCJzdWIiOiJKb2huIERvZSJ9\n#   .HwnUqTLFAMzNkMrokd0aI7c-zSJJpSVXMrYIhUyWe4s'\n\ndecoded: JWTClaims = decode(compact, secret_key, Alg.HS256)\nprint(decoded.to_dict())\n#\u003e {'iss': 'my-app', 'sub': 'John Doe'}\nprint(decoded.sub)\n#\u003e 'John Doe'\n```\n\nDefine dynamically your claims with Pydantic and easily include `'iat'` (Issued At) and `'exp'` (Expiration).\nValidate your JWT content automatically during encoding and decoding. \n\n```python\nfrom superjwt import Alg, JWTClaims, encode, decode\n\nsecret_key = \"your-secret-key-of-len-32-bytes!\"\n\nclaims = (\n    JWTClaims(iss=\"my-app\", sub=\"John Doe\")\n    .with_issued_at()\n    .with_expiration(minutes=15)\n)\n\ncompact: bytes = encode(claims, secret_key, Alg.HS256)\n\ndecoded: JWTClaims = decode(compact, secret_key, Alg.HS256)\nprint(decoded.to_dict())\n#\u003e {'iss': 'my-app', 'sub': 'John Doe', 'iat': 1767027483, 'exp': 1767028383}\nprint(decoded.exp)\n#\u003e 2025-12-29 17:13:03\n```\n\n### Custom Claims and Validation\n\nRedefine standard claims or define new custom ones. Validate automatically during encoding and decoding.\n\n```python\nfrom typing import Annotated\n\nfrom pydantic import UUID4, Field, PlainSerializer\nfrom superjwt import Alg, JWTClaims, Validation, decode, encode\nfrom superjwt.exceptions import ClaimsValidationError\n\nsecret_key = \"your-secret-key-of-len-32-bytes!\"\n\nclass MyJWTClaims(JWTClaims):\n    # redefine 'sub' as required integer\n    sub: int = Field(default=...)\n\n    # new custom claim:  'user_id' is required and must be a valid UUIDv4 string\n    user_id: Annotated[UUID4, PlainSerializer(lambda v: str(v))]\n```\n\n```python\n# Example - Validation PASSING\n\nclaims = (\n    MyJWTClaims(sub=123, user_id=\"b2a4c791-2cf4-4e41-9a20-8532129ff47c\")\n    .with_expiration(minutes=15)\n)\ncompact = encode(claims, secret_key, Alg.HS256)\ndecoded: MyJWTClaims = decode(compact, secret_key, Alg.HS256, validation=MyJWTClaims)\nprint(decoded.to_dict())\n#\u003e {'sub': 123, 'exp': 1767027591, 'user_id': 'b2a4c791-2cf4-4e41-9a20-8532129ff47c'}\n```\n\n```python\n# Example - Validation FAILING\n\n# create an invalid pydantic claims\ninvalid_claims = (\n    MyJWTClaims.model_construct(**{\"sub\": \"John Doe\", \"user_id\": \"invalid-uuid-string\"})\n    .with_issued_at()\n    .with_expiration(minutes=10)\n)\n\n# disable claims validation to create an \"invalid\" compact token\ninvalid_compact = encode(\n    invalid_claims, secret_key, Alg.HS256, validation=Validation.DISABLE\n)\ntry:\n    decode(invalid_compact, secret_key, Alg.HS256, validation=MyJWTClaims)\nexcept ClaimsValidationError as e:\n    print(\"Claims validation error:\", e)\n    #\u003e Claims validation error: Claims validation failed\n    #    claim ('sub',) = John Doe -\u003e validation failed (int_parsing): \n    #      Input should be a valid integer, unable to parse string as an integer\n    #    claim ('user_id',) = invalid-uuid-string -\u003e validation failed (value_error):\n    #      Value error, badly formed hexadecimal UUID string\n```\n\n### Compact Token Inspection\n\n\u003e [!CAUTION]\n\u003e When using `inspect()`, the JWT is not verified! Never trust the data until it is verified by `decode()`.\n\n```python\nfrom superjwt import JWSToken, inspect\n\ncompact = (\n    b\"eyJhbGciOiJOb05lIiwidHlwIjoiSldUIn0\"\n    b\".\"\n    b\"eyJjYW5fSV90cnVzdF95b3UiOiJubyJ9\"\n    b\".\"\n    b\"BsUynvYTk4w4_TCS39qAUoovSmS7hJxG4fahZGK9RrY\"\n)\n\ntoken: JWSToken = inspect(compact)\n\nprint(token.payload)\n#\u003e {'can_I_trust_you': 'no'}\n\nprint(token.headers)\n#\u003e {'alg': 'NoNe', 'typ': 'JWT'}\n```\n\n\u003ca href=\"https://ixunio.github.io/superjwt/latest/\"\u003e\u003cstrong\u003e\u003cem\u003eSee full documentation\u003c/em\u003e\u003c/strong\u003e\u003c/a\u003e\n\n## Test\n\n1. Clone repository\n\n2. Install dependencies\n    ```bash\n    pip install -e . --group test\n    ```\n3. Run tests\n    ```bash\n    pytest\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fixunio%2Fsuperjwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fixunio%2Fsuperjwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fixunio%2Fsuperjwt/lists"}