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:

```bash
# 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`:
   ```python
   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

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