# Betterauth Fastapi JWT Bridge

> Implement secure authentication bridge between Better Auth (Next.js frontend) and FastAPI (Python backend) using JWKS JWT token verification. Use this skill when users need to (1) Integrate Better Auth with FastAPI backend, (2) Implement JWT authentication with JWKS verification, (3) Set up user isolation and authorization in FastAPI endpoints, (4) Configure frontend to send authenticated API requests, or (5) Troubleshoot Better Auth + FastAPI authentication issues.

- Skill: `jsgforever/betterauth-fastapi-jwt-bridge` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add jsgforever/betterauth-fastapi-jwt-bridge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsgforever/betterauth-fastapi-jwt-bridge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jsgforever (https://skillmd.com/u/jsgforever)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jsgforever/betterauth-fastapi-jwt-bridge

---


# Better Auth + FastAPI JWT Bridge

Implement production-ready JWT authentication between Better Auth (Next.js) and FastAPI using JWKS verification for secure, stateless authentication.

## Architecture

```
User Login (Frontend)
    ↓
Better Auth → Issues JWT Token
    ↓
Frontend API Request → Authorization: Bearer <token>
    ↓
FastAPI Backend → Verifies JWT with JWKS → Returns filtered data
```

## Quick Start Workflow

### Step 1: Enable JWT in Better Auth (Frontend)

```typescript
// lib/auth.ts
import { betterAuth } from "better-auth"
import { jwt } from "better-auth/plugins"

export const auth = betterAuth({
    plugins: [jwt()],  // Enables JWT + JWKS endpoint
    // ... other config
})
```

**Database Migration Required:**

After adding JWT plugin, run migrations to create required tables:

```bash
# Next.js (Better Auth CLI)
npx @better-auth/cli migrate
```

**⚠️ IMPORTANT - Two Separate Tables Required:**

1. **`session` table must have `token` column** (core Better Auth requirement)
   - Error: `column "token" of relation "session" does not exist`
   - Fix: See [Database Schema Issues](references/troubleshooting.md#database-schema-issues)

2. **`jwks` table must exist** (JWT plugin requirement)
   - Error: `relation "jwks" does not exist`
   - Fix: See [Database Schema Issues](references/troubleshooting.md#database-schema-issues)

These are **separate migrations**. The JWT plugin creates the `jwks` table but does NOT modify the `session` table.

### Step 2: Verify JWKS Endpoint

Test the JWKS endpoint is working:

```bash
python scripts/verify_jwks.py http://localhost:3000/api/auth/jwks
```

### Step 3: Implement Backend Verification

Copy templates from `assets/` to your FastAPI project:

- `assets/jwt_verification.py` → `backend/app/auth/jwt_verification.py`
- `assets/auth_dependencies.py` → `backend/app/auth/dependencies.py`

Install dependencies:

```bash
pip install fastapi python-jose[cryptography] pyjwt cryptography httpx
```

### Step 4: Protect API Routes

```python
from app.auth.dependencies import verify_user_access

@router.get("/{user_id}/tasks")
async def get_tasks(
    user_id: str,
    user: dict = Depends(verify_user_access)
):
    # user_id is verified to match authenticated user
    return get_user_tasks(user_id)
```

### Step 5: Configure Frontend API Client

Copy `assets/api_client.ts` to `frontend/lib/api-client.ts` and use:

```typescript
import { getTasks, createTask } from "@/lib/api-client"

const tasks = await getTasks(userId)
```

**⚠️ React Component Pattern:**

Better Auth does NOT provide a `useSession()` hook. Use `authClient.getSession()` with `useEffect`:

```typescript
import { useState, useEffect } from "react"
import { authClient } from "@/lib/auth-client"

function MyComponent() {
  const [user, setUser] = useState(null)

  useEffect(() => {
    async function loadSession() {
      const session = await authClient.getSession()
      if (session?.data?.user) {
        setUser(session.data.user)
      }
    }
    loadSession()
  }, [])

  return <div>Welcome {user?.name}</div>
}
```

See [Frontend Integration Issues](references/troubleshooting.md#frontend-integration-issues) for complete examples.

## Better Auth UUID Integration (Hybrid ID Architecture)

**Problem Solved:** Better Auth uses String IDs internally, but applications often need UUID for type consistency across API routes and database foreign keys.

**Solution:** Hybrid ID approach - User table has both `id` (String, Better Auth requirement) and `uuid` (UUID, application use).

### Database Schema

```sql
CREATE TABLE "user" (
    id VARCHAR PRIMARY KEY,              -- Better Auth String ID
    uuid UUID UNIQUE NOT NULL,           -- Application UUID ⭐
    email VARCHAR UNIQUE NOT NULL,
    "emailVerified" BOOLEAN DEFAULT FALSE,
    name VARCHAR,
    "createdAt" TIMESTAMP NOT NULL,
    "updatedAt" TIMESTAMP NOT NULL
);

-- UUID auto-generated by database
ALTER TABLE "user" ALTER COLUMN uuid SET DEFAULT gen_random_uuid();

-- All foreign keys point to user.uuid
CREATE TABLE tasks (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES "user"(uuid) ON DELETE CASCADE,  -- ⭐ FK to uuid
    title VARCHAR NOT NULL,
    ...
);
```

### Frontend Configuration (Better Auth)

Add UUID generation hook and JWT custom claim:

```typescript
// lib/auth.ts
import { betterAuth } from "better-auth"
import { jwt } from "better-auth/plugins"
import { Pool } from "pg"

const pool = new Pool({ connectionString: process.env.DATABASE_URL })

export const auth = betterAuth({
  database: pool,

  // Hook to fetch database-generated UUID
  hooks: {
    user: {
      created: async ({ user }) => {
        const result = await pool.query(
          'SELECT uuid FROM "user" WHERE id = $1',
          [user.id]
        )
        const uuid = result.rows[0]?.uuid
        return { ...user, uuid }
      }
    }
  },

  // Include UUID in JWT payload
  plugins: [
    jwt({
      algorithm: "EdDSA",
      async jwt(user, session) {
        return {
          uuid: user.uuid,  // ⭐ Custom claim for backend
        }
      },
    }),
  ],
})
```

### Backend Pattern (FastAPI)

Extract UUID from JWT custom claim (not `sub`):

```python
# backend/app/auth/dependencies.py
from uuid import UUID

async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
    payload = verify_jwt_token(token)

    # Extract UUID from custom claim (not 'sub')
    user_uuid_str = payload.get("uuid")  # ⭐
    user_uuid = UUID(user_uuid_str)

    # Query by UUID
    user = await session.execute(
        select(User).where(User.uuid == user_uuid)
    )
    return user.scalar_one_or_none()

async def verify_user_match(
    user_id: UUID,  # From URL path
    current_user: User = Depends(get_current_user)
) -> User:
    # Compare UUIDs (not String IDs)
    if current_user.uuid != user_id:
        raise HTTPException(403, "Not authorized")
    return current_user
```

**Key Pattern:** Always query by `User.uuid` and validate against UUID from JWT custom claim.

## Key Components

### 1. JWKS Verification Flow

1. **Fetch JWKS** (cached) from Better Auth endpoint
2. **Extract kid** (key ID) from JWT token header
3. **Find matching public key** in JWKS by kid
4. **Verify signature** using Ed25519 public key
5. **Validate claims** (issuer, audience, expiration)
6. **Extract user info** from payload (`sub` claim)

### 2. User Isolation Pattern

Always verify `user_id` from JWT matches `user_id` in URL:

```python
if current_user["user_id"] != user_id:
    raise HTTPException(status_code=403, detail="Not authorized")
```

This prevents users from accessing other users' data.

### 3. JWT Payload Structure (Updated with UUID Integration)

```json
{
  "sub": "user_abc123",       // Better Auth String ID
  "uuid": "a1b2c3d4-e5f6...", // Application UUID (custom claim) ⭐
  "email": "user@example.com",
  "name": "User Name",
  "iat": 1234567890,          // Issued at
  "exp": 1234567890,          // Expiration
  "iss": "http://localhost:3000",
  "aud": "http://localhost:3000"
}
```

**Important:** The `uuid` custom claim is used for backend user identification and database queries.
Better Auth manages users with String IDs (`sub`), while the application uses UUIDs (`uuid`) for type consistency.

## Environment Configuration

**Frontend (.env.local):**
```bash
BETTER_AUTH_SECRET="min-32-chars-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_API_URL="http://localhost:8000"
```

**Backend (.env):**
```bash
BETTER_AUTH_URL="http://localhost:3000"
DATABASE_URL="postgresql://..."
```

## Testing & Validation

### Test JWKS Endpoint

```bash
python scripts/verify_jwks.py http://localhost:3000/api/auth/jwks
```

Expected output shows public keys with `kid`, `kty`, `crv`, and `x` fields.

### Test JWT Verification

```bash
python scripts/test_jwt_verification.py \
  --jwks-url http://localhost:3000/api/auth/jwks \
  --token "eyJhbGci..."
```

## Troubleshooting

### Authentication Issues

| Issue | Solution |
|-------|----------|
| "relation 'jwks' does not exist" | Create JWKS table migration - see [Database Schema Issues](references/troubleshooting.md#database-schema-issues) |
| "column 'token' does not exist" | Add `token` column to session table - see [Database Schema Issues](references/troubleshooting.md#database-schema-issues) |
| "Token missing UUID (uuid claim)" | Configure Better Auth hook and JWT plugin - see [UUID Integration Issues](references/troubleshooting.md#better-auth-uuid-integration-issues) |
| "User not found after registration" | Dual auth system conflict - see [UUID Integration Issues](references/troubleshooting.md#better-auth-uuid-integration-issues) |
| "authClient.useSession is not a function" | Use `authClient.getSession()` in useEffect - see [Frontend Integration Issues](references/troubleshooting.md#frontend-integration-issues) |
| "No authentication token available" | Use `session.data.session.token` not `session.session.token` - see [Frontend Integration Issues](references/troubleshooting.md#frontend-integration-issues) |
| "Unable to find matching signing key" | Clear JWKS cache in jwt_verification.py |
| "Token has expired" | Frontend needs to refresh session |
| "Invalid token claims" | Check issuer/audience match BETTER_AUTH_URL |
| 403 Forbidden (UUID mismatch) | Ensure UUID comparison, not String vs UUID - see [UUID Integration Issues](references/troubleshooting.md#better-auth-uuid-integration-issues) |

### Frontend-Backend Integration Issues (NEW - 2026-01-02)

| Issue | Root Cause | Solution |
|-------|-----------|----------|
| **Tasks not displaying despite 200 OK** | Backend returns array, frontend expects paginated object | Handle both formats with `Array.isArray()` check - see [Frontend-Backend Integration](references/troubleshooting.md#issue-tasks-not-displaying-despite-successful-api-response) |
| **Tag filtering crashes** | Backend returns tag objects `{id, name, color}`, frontend expected `number[]` | Update TypeScript types to match Pydantic schemas - see [Tag Filtering](references/troubleshooting.md#issue-tag-filtering-crashes-at-runtime) |
| **Pagination shows "NaN"** | Optional priority field used in arithmetic without null check | Add null checks with defaults for optional fields - see [Priority Sorting](references/troubleshooting.md#issue-priority-sorting-showing-nan-in-pagination) |
| **Tags not saving to database** | TaskCreate schema doesn't accept tags field | Use multi-step operation: create task, then assign tags - see [Tag Assignment](references/troubleshooting.md#issue-tags-not-inserting-into-task_tags-table) |
| **Edit form fields blank** | Uncontrolled components + field name mismatches + datetime format | Use controlled components, match field names, convert datetime - see [Edit Form](references/troubleshooting.md#issue-edit-form-not-pre-filling-reminder-time-recurrence-and-tags) |
| **500 Error: timezone comparison** | Comparing offset-naive and offset-aware datetimes | Normalize both to UTC before comparison - see [Timezone Fix](references/troubleshooting.md#issue-500-error---cant-compare-offset-naive-and-offset-aware-datetimes) |
| **Tag color validation fails** | Frontend required color, backend allows optional | Make color optional in Zod schema, provide defaults - see [Tag Color](references/troubleshooting.md#issue-tag-color-validation-failures) |
| **Tag filter checkboxes broken** | Backend returns `id: number`, FilterContext uses `string[]` | Convert IDs to strings for comparison - see [Tag Filters](references/troubleshooting.md#issue-tag-filter-checkboxes-not-working) |

**📚 Critical Reading:** See [Frontend-Backend Integration Issues](references/troubleshooting.md#frontend-backend-integration-issues) section in troubleshooting guide for detailed fixes with code examples. This section documents 8 critical issues discovered during implementation and their resolutions.

**Key Learnings:**
1. **Always read backend Pydantic schemas before writing frontend types**
2. **Handle optional fields with null checks and defaults**
3. **Use controlled components for pre-filled forms**
4. **Match field names exactly between frontend and backend**
5. **Test with actual backend responses, not mocked data**

See `references/troubleshooting.md` for detailed solutions and prevention strategies.

## Advanced Topics

### JWKS Caching Strategy

The implementation uses `@lru_cache` to cache JWKS responses:

- Cache invalidated if token has unknown `kid`
- Public keys rarely change (safe to cache)
- Reduces network calls to Better Auth

See `references/jwks-approach.md` for implementation details.

### Security Checklist

Before production:

- ✅ HTTPS only for all API calls
- ✅ Token expiration validated
- ✅ Issuer/audience claims verified
- ✅ User ID authorization enforced
- ✅ CORS properly configured
- ✅ Error messages don't leak sensitive info

See `references/security-checklist.md` for complete list.

## Resources

### scripts/
- `verify_jwks.py` - Test JWKS endpoint availability
- `test_jwt_verification.py` - Validate JWT token verification

### references/
- `jwks-approach.md` - Detailed JWKS implementation guide
- `security-checklist.md` - Production security requirements
- `troubleshooting.md` - Common issues and fixes

### assets/
- `jwt_verification.py` - Complete JWKS verification module template
- `auth_dependencies.py` - FastAPI dependencies template
- `api_client.ts` - Frontend API client template
- `better_auth_migrations.py` - Alembic migration templates for Better Auth tables (including token column fix)

## Why JWKS Over Shared Secret?

| Aspect | JWKS | Shared Secret |
|--------|------|---------------|
| Security | ✅ Asymmetric (more secure) | ⚠️ Symmetric (less secure) |
| Scalability | ✅ Multiple backends | ⚠️ Secret must be shared |
| Production | ✅ Recommended | ⚠️ Development only |
| Complexity | Medium | Simple |

**Recommendation:** Always use JWKS for production.