Flask-JWT-Extended

4.7.1 · active · verified Thu Apr 09

Flask-JWT-Extended is a Python library that provides extended JWT (JSON Web Token) integration for Flask applications. It simplifies the process of adding JWT-based authentication to your API, handling token creation, authorization, and common features like fresh tokens, blocklists, and token refreshing. The current version is 4.7.1, and it maintains a steady release cadence with active development and regular updates to support new Python and Flask versions.

Warnings

breaking Python 3.7 and 3.8 support was dropped in Flask-JWT-Extended 4.7.0. If you are on these Python versions, you must upgrade your Python environment or use a version of Flask-JWT-Extended older than 4.7.0.
Fix: Upgrade your Python version to 3.9 or newer. If not possible, pin `Flask-JWT-Extended<4.7.0`.
breaking Flask 3.0 compatibility was introduced in Flask-JWT-Extended 4.5.3. Applications using Flask 3.x must ensure they are using `flask-jwt-extended>=4.5.3` to avoid compatibility issues.
Fix: Upgrade `Flask-JWT-Extended` to version 4.5.3 or newer if using Flask 3.x. Pin `Flask-JWT-Extended<4.5.3` if using Flask <3.0.
breaking Migrating from Flask-JWT-Extended v3.x to v4.x involved significant breaking changes, including how tokens are returned (no longer a dict by default), changes to decorators, and more explicit configuration requirements.
Fix: Consult the official migration guide for detailed steps. Be prepared to update token return formats, decorator usage, and configuration settings (e.g., `JWT_SECRET_KEY`).
gotcha Flask-JWT-Extended uses `app.config["JWT_SECRET_KEY"]` for signing JWTs, which is distinct from Flask's `app.secret_key` or `app.config["SECRET_KEY"]`. Using Flask's secret key for JWT signing is a common mistake and can lead to unexpected behavior or security vulnerabilities.
Fix: Always set `app.config["JWT_SECRET_KEY"]` explicitly and ensure it is a strong, unique secret key separate from Flask's `SECRET_KEY`.
gotcha The `identity` argument passed to `create_access_token()` (and `create_refresh_token()`) should ideally be a string or a value that can be easily serialized to JSON and uniquely identifies the user. While it may accept other types, the documentation strongly encourages string identities for clarity and consistent behavior.
Fix: Ensure the value passed as `identity` is a unique string representing the user (e.g., user ID, username). If using an object, ensure it can be reliably serialized and deserialized to retrieve the identity later.

Install

pip install Flask-JWT-Extended Install latest version

Imports

JWTManager

from flask_jwt_extended import JWTManager

jwt_required

from flask_jwt_extended import jwt_required

create_access_token

from flask_jwt_extended import create_access_token

get_jwt_identity

from flask_jwt_extended import get_jwt_identity

Quickstart

This quickstart demonstrates how to initialize Flask-JWT-Extended, create a login endpoint to issue an access token, and protect another endpoint using the `@jwt_required()` decorator. It shows how to retrieve the identity of the authenticated user within a protected route. Remember to set the `FLASK_JWT_SECRET_KEY` environment variable for production environments.

import os
from flask import Flask, jsonify, request
from flask_jwt_extended import create_access_token, jwt_required, JWTManager, get_jwt_identity

app = Flask(__name__)
# Set a secret key for JWT signing. For production, use a strong, unique key.
app.config["JWT_SECRET_KEY"] = os.environ.get("FLASK_JWT_SECRET_KEY", "super-secret-dev-key")

# Initialize the Flask-JWT-Extended extension
jwt = JWTManager(app)

# A simple login route to get an access token
@app.route("/login", methods=["POST"])
def login():
    username = request.json.get("username", None)
    password = request.json.get("password", None)

    # In a real application, you'd verify these credentials against a database
    if username != "testuser" or password != "testpass":
        return jsonify({"msg": "Bad username or password"}), 401

    access_token = create_access_token(identity=username)
    return jsonify(access_token=access_token)

# A protected route that requires a valid JWT access token
@app.route("/protected", methods=["GET"])
@jwt_required()
def protected():
    # Access the identity of the current user with get_jwt_identity
    current_user = get_jwt_identity()
    return jsonify(logged_in_as=current_user), 200

if __name__ == "__main__":
    # To run:
    # 1. Set FLASK_JWT_SECRET_KEY environment variable (or it will use 'super-secret-dev-key')
    #    e.g., export FLASK_JWT_SECRET_KEY="your-strong-secret"
    # 2. Run this script: python your_app.py
    # 3. Test with curl:
    #    curl -X POST -H "Content-Type: application/json" -d '{"username":"testuser", "password":"testpass"}' http://127.0.0.1:5000/login
    #    (Copy the access_token from the response)
    #    curl -H "Authorization: Bearer <your_access_token>" http://127.0.0.1:5000/protected
    app.run(debug=True)

view raw JSON →