SuperTokens Python SDK

Common errors

• 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'))

  cause The SuperTokens Core service is not running or is not accessible at the specified `connection_uri`.
  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.

• AttributeError: module 'supertokens_python.framework' has no attribute 'flask'

  cause The framework-specific dependency (e.g., `supertokens-python[flask]`) was not installed, or the import path is incorrect.
  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`.

• ValueError: cookieDomain must be a super domain of 'localhost'

  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.
  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).

Warnings

• gotcha 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.
  Fix: Ensure the SuperTokens Core is installed and running before starting your Python application. Refer to SuperTokens documentation for core setup instructions.
• breaking Timestamps related to sessions and other features now use UTC instead of server local time.
  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.
• gotcha 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.
  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.

Install

• pip install supertokens-python Install core SDK
• pip install 'supertokens-python[flask]' # or '[fastapi]', '[django]', '[starlette]' Install with framework integration

Imports

• init

  from supertokens_python import init

• SessionRecipe

  from supertokens_python.recipe import session

• EmailPasswordRecipe

  from supertokens_python.recipe import emailpassword

• FlaskMiddleware

  from supertokens_python.framework.flask import get_middleware

Quickstart

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`.

import os
import supertokens_python
from supertokens_python.recipe import session, emailpassword

# NOTE: This example requires a running SuperTokens Core service (e.g., at http://localhost:3567)

supertokens_python.init(
    app_info=supertokens_python.AppInfo(
        app_name="My SuperTokens App",
        api_domain="http://localhost:3001", # Your backend domain
        website_domain="http://localhost:3000" # Your frontend domain
    ),
    connection_uri=os.environ.get('SUPERTOKENS_CONNECTION_URI', 'http://localhost:3567'),
    recipes=[
        session.init(), # Provides session management
        emailpassword.init() # Provides email/password login
    ]
)

# In a web framework like Flask/FastAPI/Django, you would then integrate the middleware.
# Example for Flask (requires 'supertokens-python[flask]' installed):
# from flask import Flask
# from supertokens_python.framework.flask import get_middleware
# app = Flask(__name__)
# app.register_blueprint(get_middleware())
# @app.route('/test-session')
# @session.verify_session()
# def test_session():
#     s = session.get_session() # Get current session
#     return f"Hello user {s.get_user_id()}"