JWT Authentication Skill

Expert implementation of JWT token generation, verification, and user extraction for FastAPI and Python applications.

Quick Reference

Core Workflows

1. Generate Access Token

from auth.jwt import create_access_token

# Basic token with subject
token = create_access_token(data={"sub": "user@example.com"})

# Token with custom expiry (minutes)
from datetime import timedelta
token = create_access_token(
    data={"sub": "user@example.com", "roles": ["admin"]},
    expires_delta=timedelta(minutes=15)
)

# Token with roles for RBAC
token = create_access_token(data={"sub": "user@corp.com", "roles": ["editor", "viewer"]})

Claims structure:

• sub (required): User identifier (email, ID, or username)
• exp (auto): Expiration time
• roles (optional): List of role strings for authorization
• Custom claims: Add any extra data as needed

2. Protect Endpoint with Dependency

from fastapi import APIRouter, Depends
from auth.dependencies import get_current_user

router = APIRouter()

@router.get("/protected")
def protected_route(user = Depends(get_current_user)):
    return {"message": f"Hello, {user.email}"}

3. Role-Based Access Control

from auth.dependencies import get_current_user, RoleChecker

# Define role checker
admin_only = RoleChecker(allowed_roles=["admin"])

@router.delete("/admin-only")
def admin_endpoint(user = Depends(admin_only)):
    return {"message": "Admin access granted"}

4. Extract User from JWT Payload

from auth.dependencies import get_current_user

# User model automatically extracted from JWT claims
@router.get("/me")
def get_me(user = Depends(get_current_user)):
    return {
        "email": user.email,
        "roles": user.roles,
        "is_active": user.is_active
    }

Security Checklist

• Short expiry + refresh: Access tokens expire in 15-30 minutes; implement refresh token flow for long sessions
• No sensitive data: Never put passwords, PII, or secrets in JWT claims
• Blacklist invalid: Implement token blacklist for logout (see revoked_tokens set)
• HS256 algorithm: Use HMAC-SHA256; never use algorithm="none"
• Verify expiration: Always check exp claim; reject expired tokens

Token Structure

Header:
{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:
{
  "sub": "user@example.com",
  "roles": ["user", "editor"],
  "exp": 1704067200,
  "iat": 1704063600
}

Signature: HMAC-SHA256(secret, header.payload)

User Model

class User:
    email: str
    roles: List[str]
    is_active: bool = True

    @classmethod
    def from_payload(cls, payload: dict) -> "User":
        """Extract User from decoded JWT payload."""
        return cls(
            email=payload.get("sub", ""),
            roles=payload.get("roles", []),
            is_active=payload.get("is_active", True)
        )

Integration with @auth-integration Frontend

The backend JWT implementation pairs with the frontend auth integration skill:

1. Backend: auth/jwt.py and auth/dependencies.py
2. Frontend: Use auth-integration skill for React/Next.js auth context
3. Token flow:
   • Frontend stores token in memory/storage after login
   • Frontend includes Authorization: Bearer <token> header
   • Backend HTTPBearer() dependency validates and extracts user
   • Failed verification returns 401 Unauthorized

File Outputs

Configuration

Set these environment variables:

• JWT_SECRET_KEY: Long random string (at least 32 chars)
• JWT_ALGORITHM: "HS256" (default)
• JWT_EXPIRATION_MINUTES: 15 (recommended)

Quality Gates

Before marking complete:

• Tokens use HS256 algorithm
• Expiration set to 15-30 minutes
• No sensitive data in claims
• Blacklist mechanism implemented for logout
• Integration with auth-integration frontend skill documented