JWT Management

JSON Web Token creation, validation, and authentication

JWT Token Structure

The application uses JSON Web Tokens (JWT) for session management. Tokens are stored in httpOnly cookies for security.

Token Payload

sub · string · required

Subject - User ID as a string

exp · integer · required

Expiration time - Unix timestamp when the token expires

iat · integer · required

Issued at - Unix timestamp when the token was created

Token Generation

Tokens are created using the create_access_token function in app/auth/jwt_utils.py:6.

Implementation

def create_access_token(user_id: int) -> str:
    """Create a JWT token for the given user ID."""
    expire = datetime.now(timezone.utc) + timedelta(
        minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
    )
    payload = {
        "sub": str(user_id),
        "exp": expire,
        "iat": datetime.now(timezone.utc),
    }
    return jwt.encode(payload, settings.SECRET_KEY, algorithm=settings.ALGORITHM)

Configuration

SECRET_KEY · string · required

Secret key used for signing JWT tokens. Must be kept secure.

ALGORITHM · string · default: "HS256"

Algorithm used for JWT encoding/decoding

ACCESS_TOKEN_EXPIRE_MINUTES · integer

Token expiration time in minutes

---

Token Validation

Tokens are validated using the decode_access_token function in app/auth/jwt_utils.py:17.

Implementation

def decode_access_token(token: str) -> int | None:
    """Decode JWT and return user_id, or None if invalid/expired."""
    try:
        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
        user_id = payload.get("sub")
        if user_id is None:
            return None
        return int(user_id)
    except JWTError:
        return None

Validation Rules

1. Signature Verification - Token must be signed with the correct SECRET_KEY
2. Expiration Check - Token must not be expired
3. Subject Presence - Token must contain a “sub” claim with the user ID
4. Algorithm Match - Token must use the configured algorithm

Return Values

user_id · integer

The user ID extracted from the token

None · null

Returned when:

• Token signature is invalid
• Token is expired
• Token is malformed
• “sub” claim is missing

---

Authentication Dependency

The get_current_user dependency function validates the JWT cookie and retrieves the authenticated user from the database.

Implementation

Defined in app/auth/dependencies.py:9:

Function

async def get_current_user(
    access_token: str | None = Cookie(default=None),
    db: AsyncSession = Depends(get_db),
) -> User:
    """
    Read the httpOnly JWT cookie, decode it, and return the User.
    Raises 401 if missing, invalid, or expired.
    """
    if not access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    user_id = decode_access_token(access_token)
    if user_id is None:
        raise HTTPException(status_code=401, detail="Invalid or expired token")

    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    if not user:
        raise HTTPException(status_code=401, detail="User not found")

    return user

Behavior

1. Extracts the access_token from the httpOnly cookie
2. Decodes and validates the JWT token
3. Queries the database for the user by ID
4. Returns the User object if found
5. Raises HTTPException 401 for any authentication failure

Error Responses

401 · error

Not authenticated - Cookie is missing

401 · error

Invalid or expired token - JWT validation failed

401 · error

User not found - User ID from token doesn’t exist in database

---

Logout

Request

POST /auth/logout

Clears the authentication cookie, effectively logging out the user.

Response

message · string

Confirmation message: “Logged out”

Behavior

• Deletes the access_token httpOnly cookie
• Cookie deletion respects the same security settings (secure, samesite) as when it was set
• No authentication required (can be called even if not logged in)

200 Response

{
  "message": "Logged out"
}