PropelAuth Python SDK

Common errors

• TypeError: 'User' object is not subscriptable

  cause Attempting to unpack a PropelAuth response object (like the `User` object) using dictionary unpacking syntax (`**`) after it was changed to an explicit datatype in v4.x.
  fix Access user attributes directly (e.g., `user.user_id`, `user.email`). If you need a dictionary representation, you might need to convert it explicitly if the library doesn't provide a `.to_dict()` method.

• propelauth_py.errors.UnauthorizedException: Invalid access token

  cause The provided Authorization header is missing, malformed, or contains an expired/invalid access token. It can also occur if the `AUTH_URL` or `API_KEY` used during initialization are incorrect.
  fix Ensure the `Authorization` header is present and in the format `Bearer {TOKEN}`. Verify that your `AUTH_URL` and `API_KEY` are correct and match your PropelAuth project settings. Check if the token itself is valid and not expired.

• ModuleNotFoundError: No module named 'propelauth_py'

  cause The `propelauth-py` library is not installed in the current Python environment or is not included in the deployment package for serverless functions (e.g., AWS Lambda with Chalice).
  fix Run `pip install propelauth-py` to install the library. For serverless applications, ensure `propelauth-py` is listed in your `requirements.txt` file (or equivalent) so it gets bundled with your deployment.

Warnings

• breaking In v4.x, response objects (e.g., from validation or API calls) are now explicit datatypes with proper type hints instead of plain dictionaries. Attempting to unpack a response using the `**` operator will result in a `TypeError`.
  Fix: Access attributes directly (e.g., `user.user_id`) instead of treating the object as a dictionary for unpacking. Dictionary-style key lookup (`user["user_id"]`) still works, but direct attribute access is preferred.
• gotcha The core `propelauth-py` library provides general authentication functionalities. However, for specific web frameworks like FastAPI, Flask, or Django REST Framework, dedicated libraries (`propelauth-fastapi`, `propelauth-flask`, `propelauth-django-rest-framework`) offer a more integrated and 'first-class' experience for route protection and user handling.
  Fix: Consider using the framework-specific PropelAuth library if available for your chosen web framework to leverage native integration patterns.
• gotcha By default, the PropelAuth Python library logs exceptions using Python's standard logging module. This might lead to sensitive information in logs if not properly managed.
  Fix: To disable exception logging, pass `log_exceptions=False` during initialization (e.g., `init_base_auth(..., log_exceptions=False)`) or configure it globally using `propelauth_py.configure_logging(log_exceptions=False)`.
• gotcha When using asynchronous operations, remember to use the `_async` suffix for initialization functions (e.g., `init_base_async_auth` instead of `init_base_auth`). All subsequent API calls will then be asynchronous.
  Fix: Ensure you import and use `init_base_async_auth` for asynchronous contexts. This often requires an `httpx.AsyncClient()` if a custom client is needed.

Install

• pip install propelauth-py Install stable version

Imports

• init_base_auth

  from propelauth_py import init_base_auth

  Synchronous initialization of the PropelAuth client.
• init_base_async_auth

  from propelauth_py import init_base_async_auth

  Asynchronous initialization of the PropelAuth client.
• UnauthorizedException

  from propelauth_py.errors import UnauthorizedException

  Exception raised when an access token is invalid or unauthorized.
• User

  from propelauth_py import User

  Represents an authenticated user object returned by validation functions.

Quickstart

This quickstart demonstrates how to initialize the PropelAuth client and validate an access token. It uses environment variables for secure configuration. Upon successful validation, it prints user and organization details. It also includes commented-out code for an example backend API call (e.g., creating a magic link).

import os
from propelauth_py import init_base_auth, UnauthorizedException

# Your PropelAuth Auth URL and API Key from your PropelAuth dashboard
AUTH_URL = os.environ.get('PROPELAUTH_AUTH_URL', 'YOUR_AUTH_URL')
API_KEY = os.environ.get('PROPELAUTH_API_KEY', 'YOUR_API_KEY')

if not AUTH_URL or AUTH_URL == 'YOUR_AUTH_URL' or not API_KEY or API_KEY == 'YOUR_API_KEY':
    print("Please set PROPELAUTH_AUTH_URL and PROPELAUTH_API_KEY environment variables")
    exit(1)

try:
    auth = init_base_auth(AUTH_URL, API_KEY)
    
    # Simulate an Authorization header from an incoming request
    # In a real application, this would come from a client request
    mock_auth_header = "Bearer a_mock_jwt_token"
    
    # Validate the access token and get user information
    user = auth.validate_access_token_and_get_user(mock_auth_header)
    
    print(f"Successfully authenticated user: {user.user_id}")
    print(f"User email: {user.email}")
    if user.orgs:
        print("User belongs to organizations:")
        for org_member_info in user.orgs:
            print(f"  - Org ID: {org_member_info.org_id}, Name: {org_member_info.org_name}, Roles: {org_member_info.roles}")
            
    # Example of calling a backend API to create a magic link
    # Note: This requires appropriate permissions on your API key
    # magic_link_response = auth.create_magic_link("test@example.com")
    # print(f"Magic link URL: {magic_link_link.url}")

except UnauthorizedException:
    print("Authentication failed: Invalid access token or configuration.")
except Exception as e:
    print(f"An error occurred: {e}")