Workos Python

WorkOS AuthKit for Python

Step 1: Fetch SDK Documentation (BLOCKING)

STOP. Do not proceed until complete.

WebFetch: https://raw.githubusercontent.com/workos/workos-python/main/README.md

Also fetch the AuthKit quickstart for reference: WebFetch: https://workos.com/docs/authkit/vanilla/python

The README is the source of truth for SDK API usage. If this skill conflicts with README, follow README.

Step 2: Detect Framework

Examine the project to determine which Python web framework is in use:

manage.py exists?                        → Django
  settings.py has django imports?        → Confirmed Django

Gemfile/requirements has 'fastapi'?      → FastAPI
  main.py has FastAPI() instance?        → Confirmed FastAPI

requirements has 'flask'?               → Flask
  server.py/app.py has Flask() instance? → Confirmed Flask

None of the above?                       → Vanilla Python (use Flask quickstart pattern)

Adapt all subsequent steps to the detected framework. Do not force one framework onto another.

Step 3: Pre-Flight Validation

Package Manager Detection

uv.lock exists?                          → uv add
pyproject.toml has [tool.poetry]?        → poetry add
Pipfile exists?                          → pipenv install
requirements.txt exists?                 → pip install (+ append to requirements.txt)
else                                     → pip install

Environment Variables

Check .env for:

• WORKOS_API_KEY - starts with sk_
• WORKOS_CLIENT_ID - starts with client_

Step 4: Install SDK

Install using the detected package manager:

# uv
uv add workos python-dotenv

# poetry
poetry add workos python-dotenv

# pip
pip install workos python-dotenv

If using requirements.txt, also append workos and python-dotenv to it.

Verify: python -c "import workos; print('OK')"

Step 5: Integrate Authentication

If Django

1. Configure settings.py — add import os + from dotenv import load_dotenv + load_dotenv() at top. Add WORKOS_API_KEY and WORKOS_CLIENT_ID from os.environ.get().
2. Create auth views — create auth_views.py (or add to existing views):
   • login_view: call SDK's get_authorization_url() with provider='authkit', redirect
   • callback_view: call authenticate_with_code() with the code param, store user in request.session
   • logout_view: flush session, redirect
3. Add URL patterns — add auth/login/, auth/callback/, auth/logout/ to urls.py
4. Update templates — add login/logout links using {% url %} tags

If Flask

Follow the quickstart pattern exactly:

1. Initialize WorkOS client in server.py / app.py:

   from workos import WorkOSClient
   workos = WorkOSClient(api_key=os.getenv("WORKOS_API_KEY"), client_id=os.getenv("WORKOS_CLIENT_ID"))
   

2. Create /login route — call workos.user_management.get_authorization_url(provider="authkit", redirect_uri="..."), redirect
3. Create /callback route — call workos.user_management.authenticate_with_code(code=code), set session cookie
4. Create /logout route — clear session, redirect
5. Update home route — show user info if session exists

If FastAPI

1. Initialize WorkOS client in main app file
2. Create /login endpoint — generate auth URL, return RedirectResponse
3. Create /callback endpoint — exchange code, store in session/cookie
4. Create /logout endpoint — clear session
5. Use Depends() for auth middleware on protected routes

If Vanilla Python (no framework detected)

Install Flask and follow the Flask pattern above. This matches the official quickstart.

Step 6: Environment Setup

Create/update .env with WorkOS credentials. Do NOT overwrite existing values.

WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...

Step 7: Verification Checklist

# 1. SDK importable
python -c "import workos; print('OK')"

# 2. Credentials configured
python -c "
from dotenv import load_dotenv; import os; load_dotenv()
assert os.environ.get('WORKOS_API_KEY','').startswith('sk_'), 'Missing WORKOS_API_KEY'
assert os.environ.get('WORKOS_CLIENT_ID','').startswith('client_'), 'Missing WORKOS_CLIENT_ID'
print('Credentials OK')
"

# 3. Framework-specific check
# Django: python manage.py check
# Flask: python -m py_compile server.py
# FastAPI: python -m py_compile main.py

Error Recovery

"ModuleNotFoundError: No module named 'workos'"

Re-run the install command for the detected package manager.

Django: "CSRF verification failed"

Auth callback receives GET requests from WorkOS. Ensure callback view uses GET, not POST. Or add @csrf_exempt.

Flask: Session not persisting

Ensure app.secret_key is set (required for Flask sessions).

Virtual environment not active

Check for .venv/, venv/, or poetry-managed environments. Activate before running install.