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

// 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
})

undefined

**⚠️ 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.

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

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

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)

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

const tasks = await getTasks(userId)

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>
}

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

// 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
        }
      },
    }),
  ],
})

undefined

# 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()

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

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

{
  "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"
}

BETTER_AUTH_SECRET="min-32-chars-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_API_URL="http://localhost:8000"

BETTER_AUTH_URL="http://localhost:3000"
DATABASE_URL="postgresql://..."

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

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