{"id":10275,"library":"supertokens-python","title":"SuperTokens Python SDK","description":"SuperTokens Python SDK, version 0.31.2, provides a comprehensive solution for user authentication and session management in Python applications. It integrates with various web frameworks and offers recipes like email/password, social login, and multi-factor authentication. Releases are frequent, with multiple patch and minor versions often appearing monthly to add features and fix bugs.","status":"active","version":"0.31.2","language":"en","source_language":"en","source_url":"https://github.com/supertokens/supertokens-python","tags":["authentication","auth","session management","web security","jwt","oauth","mfa","openid"],"install":[{"cmd":"pip install supertokens-python","lang":"bash","label":"Install core SDK"},{"cmd":"pip install 'supertokens-python[flask]' # or '[fastapi]', '[django]', '[starlette]'","lang":"bash","label":"Install with framework integration"}],"dependencies":[{"reason":"Used for internal API calls to the SuperTokens Core.","package":"httpx","optional":false},{"reason":"Used for sending emails (e.g., password reset, email verification) if email-based recipes are enabled.","package":"aiosmtplib","optional":true},{"reason":"Used for extracting the top-level domain from hostnames for cookie configuration.","package":"tldextract","optional":false}],"imports":[{"symbol":"init","correct":"from supertokens_python import init"},{"symbol":"SessionRecipe","correct":"from supertokens_python.recipe import session"},{"symbol":"EmailPasswordRecipe","correct":"from supertokens_python.recipe import emailpassword"},{"symbol":"FlaskMiddleware","correct":"from supertokens_python.framework.flask import get_middleware"}],"quickstart":{"code":"import os\nimport supertokens_python\nfrom supertokens_python.recipe import session, emailpassword\n\n# NOTE: This example requires a running SuperTokens Core service (e.g., at http://localhost:3567)\n\nsupertokens_python.init(\n    app_info=supertokens_python.AppInfo(\n        app_name=\"My SuperTokens App\",\n        api_domain=\"http://localhost:3001\", # Your backend domain\n        website_domain=\"http://localhost:3000\" # Your frontend domain\n    ),\n    connection_uri=os.environ.get('SUPERTOKENS_CONNECTION_URI', 'http://localhost:3567'),\n    recipes=[\n        session.init(), # Provides session management\n        emailpassword.init() # Provides email/password login\n    ]\n)\n\n# In a web framework like Flask/FastAPI/Django, you would then integrate the middleware.\n# Example for Flask (requires 'supertokens-python[flask]' installed):\n# from flask import Flask\n# from supertokens_python.framework.flask import get_middleware\n# app = Flask(__name__)\n# app.register_blueprint(get_middleware())\n# @app.route('/test-session')\n# @session.verify_session()\n# def test_session():\n#     s = session.get_session() # Get current session\n#     return f\"Hello user {s.get_user_id()}\"\n","lang":"python","description":"Initializes the SuperTokens SDK with application information, connection to the SuperTokens Core, and the desired authentication recipes. It's crucial to have the SuperTokens Core service running separately and accessible via `connection_uri`."},"warnings":[{"fix":"Ensure the SuperTokens Core is installed and running before starting your Python application. Refer to SuperTokens documentation for core setup instructions.","message":"SuperTokens Python SDK requires a running SuperTokens Core service (separate process/container) to function. The SDK connects to this core via the `connection_uri` parameter during initialization.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Applications relying on session expiry or creation times in local timezones should update their logic to account for UTC timestamps. This change improves consistency across different environments.","message":"Timestamps related to sessions and other features now use UTC instead of server local time.","severity":"breaking","affected_versions":">=0.28.0"},{"fix":"Explicitly configure `cookie_domain` in `session.init()` if needed. For `tldextract` HTTP requests, set `allow_unverified_http_requests_for_tld_extract=False` in `supertokens_python.init()` if your environment restricts outbound HTTP calls or for performance reasons.","message":"The `cookieDomain` configuration requires careful setup, especially in production environments or when using different subdomains. `tldextract` is used to determine the appropriate domain for cookies, and its HTTP requests can be disabled.","severity":"gotcha","affected_versions":"All versions, specifically >=0.29.0 for `tldextract` control"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Start the SuperTokens Core service and ensure its port matches the `connection_uri` in your `supertokens_python.init()` call. Verify firewall rules or container network settings if running in a containerized environment.","cause":"The SuperTokens Core service is not running or is not accessible at the specified `connection_uri`.","error":"HTTPConnectionPool(host='localhost', port=3567): Max retries exceeded with url: /hello (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at ...>: Failed to establish a new connection: [Errno 111] Connection refused'))"},{"fix":"Ensure you install the package with the correct framework extra: `pip install 'supertokens-python[flask]'` for Flask, `[fastapi]` for FastAPI, etc. Then use the correct import, e.g., `from supertokens_python.framework.flask import get_middleware`.","cause":"The framework-specific dependency (e.g., `supertokens-python[flask]`) was not installed, or the import path is incorrect.","error":"AttributeError: module 'supertokens_python.framework' has no attribute 'flask'"},{"fix":"Ensure `app_info.api_domain` and `app_info.website_domain` are correctly set. For development on `localhost`, you might need to explicitly set `cookie_domain=None` or ensure your frontend and backend are on the same base domain (e.g., `localhost:3000` and `localhost:3001` usually works).","cause":"The `app_info.api_domain` or `app_info.website_domain` is incorrectly configured such that the cookie domain cannot be automatically determined or is invalid for the specified domains.","error":"ValueError: cookieDomain must be a super domain of 'localhost'"}]}