Adopt JWT Authentication using Client Credentials Flow for protected API routes

[nanotaboada]

Description

Secure the API's mutating endpoints (POST, PUT, and DELETE) by introducing JWT-based authentication following the OAuth 2.0 Client Credentials Flow.

In this model, trusted machine-to-machine clients can obtain a short-lived JWT by submitting their client_id and client_secret to a dedicated authentication endpoint. This token is then included in the Authorization header to access protected resources.

sequenceDiagram
    participant Client as Client (Machine-to-Machine app)
    participant Server as Server (FastAPI RESTful API) 

    Note over Client,Server: Step 1 - Obtain Access Token

    Client->>Server: POST /auth/token (client_id, client_secret)
    Server-->>Client: 200 (OK) { access_token, expires_in, token_type }

    Note over Client,Server: Step 2 - Use Token to Access Protected Resources

    Client->>Server: POST /{resource}/{id} (Authorization: Bearer {access_token})
    Server-->>Client: 201 (Created)

    Client->>Server: PUT /{resource}/{id} (Authorization: Bearer {access_token})
    Server-->>Client: 204 (No Content)

    Client->>Server: DELETE /{resource}/{id} (Authorization: Bearer {access_token})
    Server-->>Client: 204 (No Content)

Loading

This mechanism enhances API security by ensuring only authenticated clients can perform data mutations, while maintaining statelessness.

Proposed Solution

• Add an /auth/token route to issue JWTs to clients with valid credentials.
• Introduce a simple in-memory (or configurable) client registry (client_id, client_secret).
• Secure mutating routes in player_route.py using a dependency that validates and decodes the incoming JWT.
• Configure token expiration (e.g., 60 minutes) and signing via a secret key from environment/config.
• Include test coverage and update Postman collection for authentication.

Suggested Approach

1. Install dependencies

pip install python-jose[cryptography] python-dotenv

2. Create routes/auth_route.py:

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel
from jose import jwt
from datetime import datetime, timedelta

router = APIRouter(prefix="/auth", tags=["Auth"])

ALGORITHM = "HS256"
MINUTES = 60

# Ideally, load these from secure config or environment variables
CLIENT_ID = "foobarbaz"
CLIENT_SECRET = "#!_7h3qu1ck8r0wnf0xjump50v3r7h3l42yd09=@42"
KEY = "1LnBfWcu7gTDmqT41QCW4ANu1xsHMcseingKWruVveM="


class TokenModel(BaseModel):
    grant_type: str
    client_id: str
    client_secret: str


@router.post("/token")
def get_token(data: TokenModel):
    if data.grant_type != "client_credentials":
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Unsupported grant_type. Must be 'client_credentials'."
        )

    if data.client_id != CLIENT_ID or data.client_secret != CLIENT_SECRET:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid client credentials"
        )

    expire = datetime.utcnow() + timedelta(minutes=MINUTES)
    payload = {
        "sub": data.client_id,
        "exp": expire,
        "scope": "write"
    }

    token = jwt.encode(payload, KEY, algorithm=ALGORITHM)

    return {
        "access_token": token,
        "token_type": "bearer",
        "expires_in": MINUTES * 60
    }

3. Create services/auth_dependency.py:

from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from jose import jwt, JWTError
import os

security = HTTPBearer()
ALGORITHM = "HS256"

# These values should be loaded from a secure configuration or environment variables
KEY = "1LnBfWcu7gTDmqT41QCW4ANu1xsHMcseingKWruVveM="


def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    token = credentials.credentials
    try:
        payload = jwt.decode(token, KEY, algorithms=[ALGORITHM])
    except JWTError:
        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Invalid or expired token")
    return payload

4. Secure mutating routes in routes/player_route.py:

from services.auth_dependency import verify_token

@router.post("/", dependencies=[Depends(verify_token)])
def create_player(...): ...

5. Sample token request with curl

curl -X POST http://localhost:9000/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "foobarbaz",
    "client_secret": "#!_7h3qu1ck8r0wnf0xjump50v3r7h3l42yd09_@42"
  }'

Acceptance Criteria

• /auth/token endpoint issues valid JWT for known clients
• POST, PUT, DELETE routes are secured and reject unauthenticated requests
• Token expires after configured time; expired tokens are rejected
• Protected routes return 403 Forbidden for invalid/missing JWTs
• Configuration (e.g., JWT_SECRET) is sourced from .env or config
• Unit tests cover both authentication and route protection
• Postman collection updated with new auth flow

[coderabbitai]

🤖 CodeRabbit Planning

Planning is in progress. This will take a moment...

[coderabbitai]

Coding Plan

Approach

Implement JWT-based authentication using OAuth2 Client Credentials Flow to secure mutating endpoints (POST, PUT, DELETE) in the player API. Clients will authenticate via /auth/token using client_id/client_secret to receive a JWT, which must be included in the Authorization header for protected operations.

Observations

This FastAPI application follows a clean architecture with function-based services, async database operations, and dependency injection using Depends(). Routes are organized in separate modules and registered via include_router in main.py. The project currently has no authentication, middleware, or structured configuration management—only basic environment variable usage for database configuration. Testing uses pytest with fixtures and follows AAA patterns with "Given-When-Then" naming conventions.

Assumptions

Assumption 1: JWT Library Selection

Options Considered:

• python-jose: Suggested in ticket but has security advisories and limited maintenance
• PyJWT: Actively maintained (latest release November 2024), widely adopted, better security posture

Chosen Option: PyJWT

Rationale: provides better long-term maintainability, active security updates, and aligns with current best practices for FastAPI JWT implementations. The API is similar enough that the suggested approach remains valid with minimal adjustments.

Assumption 2: Configuration Management Approach

Options Considered:

• Hardcoded constants with os.getenv() calls: Simple but lacks validation and type safety
• pydantic-settings BaseSettings: Structured configuration with validation and type hints

Chosen Option: pydantic-settings with BaseSettings

Rationale: this is the recommended FastAPI pattern for configuration management, provides automatic validation, type safety, and .env file support. It aligns with modern FastAPI best practices and makes configuration more maintainable.

Assumption 3: datetime Handling for JWT Expiration

Options Considered:

• Continue using datetime.utcnow(): Works but deprecated, will show warnings
• Use timezone-aware datetime.now(timezone.utc): Python 3.12 compatible, best practice

Chosen Option: Timezone-aware datetime with datetime.now(timezone.utc)

Rationale: ensures compatibility with Python 3.12+, follows current best practices, and avoids deprecation warnings. PyJWT handles timezone-aware datetimes correctly.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Infrastructure and Configuration Setup

Establish the foundation for JWT authentication by installing necessary dependencies and creating a centralized configuration system that securely manages secrets and authentication parameters.

Task 1: Install Authentication Dependencies

Add required packages to the project for JWT operations, configuration management, and environment variable handling.

• Add PyJWT to requirements.txt for JWT encoding/decoding operations
• Add pydantic-settings for structured configuration management with validation
• Add python-dotenv to enable .env file support for local development

Task 2: Create Configuration Module

Establish a centralized configuration system using pydantic-settings to manage JWT secrets, token parameters, and client credentials.

• Create new config/settings.py with BaseSettings class
• Define JWT configuration fields: secret key (JWT_SECRET), algorithm (default HS256), token expiration minutes (default 60)
• Define client credentials fields: CLIENT_ID and CLIENT_SECRET loaded from environment variables
• Configure model_config to load from .env file with appropriate precedence
• Use Field() for sensitive fields to require explicit environment variable setting

Task 3: Create Environment Template

Provide developers with a reference for required environment variables.

• Create .env.example file documenting all required authentication environment variables
• Include placeholder values for JWT_SECRET, CLIENT_ID, CLIENT_SECRET
• Add comments explaining how to generate secure secrets (e.g., using Python secrets module)
• Update .gitignore to ensure .env is excluded from version control

🤖 Prompt for AI agents

Set up JWT authentication infrastructure by adding dependencies and
configuration management.

Add PyJWT, pydantic-settings, and python-dotenv to requirements.txt

Create config/settings.py with BaseSettings class:
- Add JWT_SECRET, ALGORITHM (default HS256), TOKEN_EXPIRATION_MINUTES (default
60) fields
- Add CLIENT_ID and CLIENT_SECRET fields
- Configure model_config to load from .env file
- Use Field() to mark sensitive fields as required

Create .env.example with placeholders for JWT_SECRET, CLIENT_ID, CLIENT_SECRET
and comments on generating secure secrets

Update .gitignore to exclude .env file

Phase 2: Authentication Endpoint and Route Protection

Implement the token issuance endpoint and create reusable dependencies for verifying JWT tokens on protected routes.

Task 1: Create Token Issuance Endpoint

Build the /auth/token endpoint that validates client credentials and issues JWTs following OAuth2 Client Credentials Flow.

• Create new routes/auth_route.py with APIRouter configured with prefix="/auth" and tags=["Auth"]
• Define TokenRequest pydantic model with grant_type, client_id, client_secret fields
• Implement POST /token endpoint that validates grant_type is "client_credentials"
• Validate client credentials against values from settings
• Generate JWT payload with sub (client_id), exp (using timezone-aware datetime.now(timezone.utc) + timedelta), and scope claims
• Use PyJWT's jwt.encode() with settings.JWT_SECRET and settings.ALGORITHM
• Return response with access_token, token_type="bearer", and expires_in in seconds
• Handle invalid credentials with 401 Unauthorized status
• Handle unsupported grant types with 400 Bad Request status

Task 2: Create Token Verification Dependency

Implement a reusable FastAPI dependency that extracts and validates JWT tokens from Authorization headers.

• Create new services/auth_service.py following existing function-based service pattern
• Use FastAPI's HTTPBearer security scheme for extracting Bearer tokens
• Create verify_token() function that accepts HTTPAuthorizationCredentials from HTTPBearer
• Decode JWT using PyJWT's jwt.decode() with settings.JWT_SECRET and algorithms list
• Validate token expiration (PyJWT handles this automatically)
• Return decoded payload on success
• Raise HTTPException with 403 Forbidden status for invalid/expired tokens
• Use JWTError exception handling to catch all JWT-related failures

Task 3: Register Authentication Router

Make the authentication endpoint available in the application.

• Import auth_route in main.py
• Add app.include_router(auth_route.api_router) alongside existing player and health routers

Task 4: Secure Player Mutating Endpoints

Protect POST, PUT, and DELETE operations in player routes using the token verification dependency.

• Update routes/player_route.py to import verify_token from services.auth_service
• Add Depends(verify_token) to the dependencies parameter of POST /players/ endpoint decorator
• Add Depends(verify_token) to the dependencies parameter of PUT /players/{player_id} endpoint decorator
• Add Depends(verify_token) to the dependencies parameter of DELETE /players/{player_id} endpoint decorator
• Leave GET endpoints unprotected (read operations remain public)

🤖 Prompt for AI agents

Implement OAuth2 Client Credentials Flow with token issuance and route
protection.

Create routes/auth_route.py:
- Define APIRouter with prefix="/auth" and tags=["Auth"]
- Create TokenRequest model with grant_type, client_id, client_secret fields
- Implement POST /token endpoint that validates grant_type="client_credentials"
and client credentials
- Generate JWT with sub, exp (using datetime.now(timezone.utc) + timedelta),
scope claims
- Use PyJWT's jwt.encode() with settings values
- Return access_token, token_type="bearer", expires_in
- Return 401 for invalid credentials, 400 for unsupported grant_type

Create services/auth_service.py:
- Use HTTPBearer security scheme
- Implement verify_token() function accepting HTTPAuthorizationCredentials
- Decode JWT using PyJWT's jwt.decode() with settings
- Return decoded payload on success
- Raise HTTPException 403 for invalid/expired tokens using JWTError handling

Update main.py to register auth router

Update routes/player_route.py:
- Import verify_token from services.auth_service
- Add Depends(verify_token) to POST, PUT, DELETE endpoints
- Keep GET endpoints public

Phase 3: Testing and Documentation

Create comprehensive test coverage for authentication flows and update documentation to reflect the new authentication requirements.

Task 1: Create Authentication Test Fixtures

Build reusable test fixtures that enable testing both authenticated and unauthenticated scenarios.

• Update tests/conftest.py to add settings fixture that provides test configuration
• Create mock_auth_dependency fixture that overrides verify_token to bypass authentication
• Create authenticated_client fixture that sets up app.dependency_overrides for auth-free testing
• Create helper function to generate valid test tokens using test JWT secrets
• Ensure fixture teardown properly clears dependency_overrides to prevent test pollution

Task 2: Test Authentication Endpoint

Verify token issuance behavior for various credential scenarios.

• Create new tests/test_auth.py following existing test patterns
• Test successful token generation with valid client credentials (check response structure, token_type, expires_in)
• Test authentication failure with invalid client_id (expect 401)
• Test authentication failure with invalid client_secret (expect 401)
• Test rejection of unsupported grant_type values (expect 400)
• Test that issued tokens can be decoded and contain correct claims (sub, exp, scope)

Task 3: Test Protected Endpoints

Verify that mutating endpoints correctly enforce authentication requirements.

• Update tests/test_main.py to add tests for authentication on protected endpoints
• Test POST /players/ without Authorization header (expect 403)
• Test PUT /players/{id} without Authorization header (expect 403)
• Test DELETE /players/{id} without Authorization header (expect 403)
• Test POST /players/ with valid token (expect 201 using dependency override)
• Test that expired tokens are rejected (expect 403)
• Test that malformed tokens are rejected (expect 403)
• Verify GET endpoints remain accessible without authentication

Task 4: Update Documentation

Provide users with guidance on using the authenticated API.

• Update Postman collection to include /auth/token request example with client credentials
• Add environment variables to Postman collection for access_token storage
• Configure protected endpoint requests to use {{access_token}} from environment
• Update project README with authentication section explaining client credentials flow
• Document required environment variables and how to configure them
• Include curl examples for obtaining and using tokens

🤖 Prompt for AI agents

Create comprehensive test coverage and update API documentation.

Update tests/conftest.py:
- Add settings fixture for test configuration
- Create mock_auth_dependency fixture to override verify_token
- Create authenticated_client fixture using app.dependency_overrides
- Add helper function to generate valid test tokens
- Ensure proper teardown of dependency_overrides

Create tests/test_auth.py:
- Test successful token generation with valid credentials (verify response
structure, token_type, expires_in)
- Test 401 responses for invalid client_id and client_secret
- Test 400 for unsupported grant_type
- Test token decoding and claim validation (sub, exp, scope)

Update tests/test_main.py:
- Test 403 responses for POST, PUT, DELETE /players/ without auth header
- Test successful POST with valid token using dependency override
- Test 403 for expired and malformed tokens
- Verify GET endpoints work without authentication

Update documentation:
- Add /auth/token request to Postman collection with client credentials
- Configure Postman environment variables for access_token
- Update protected requests to use {{access_token}}
- Add authentication section to README with client credentials flow explanation
- Document environment variables and include curl examples

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up JWT authentication infrastructure by adding dependencies and
configuration management.

Add PyJWT, pydantic-settings, and python-dotenv to requirements.txt

Create config/settings.py with BaseSettings class:
- Add JWT_SECRET, ALGORITHM (default HS256), TOKEN_EXPIRATION_MINUTES (default
60) fields
- Add CLIENT_ID and CLIENT_SECRET fields
- Configure model_config to load from .env file
- Use Field() to mark sensitive fields as required

Create .env.example with placeholders for JWT_SECRET, CLIENT_ID, CLIENT_SECRET
and comments on generating secure secrets

Update .gitignore to exclude .env file
===============================================================================

Task: 2

Implement OAuth2 Client Credentials Flow with token issuance and route
protection.

Create routes/auth_route.py:
- Define APIRouter with prefix="/auth" and tags=["Auth"]
- Create TokenRequest model with grant_type, client_id, client_secret fields
- Implement POST /token endpoint that validates grant_type="client_credentials"
and client credentials
- Generate JWT with sub, exp (using datetime.now(timezone.utc) + timedelta),
scope claims
- Use PyJWT's jwt.encode() with settings values
- Return access_token, token_type="bearer", expires_in
- Return 401 for invalid credentials, 400 for unsupported grant_type

Create services/auth_service.py:
- Use HTTPBearer security scheme
- Implement verify_token() function accepting HTTPAuthorizationCredentials
- Decode JWT using PyJWT's jwt.decode() with settings
- Return decoded payload on success
- Raise HTTPException 403 for invalid/expired tokens using JWTError handling

Update main.py to register auth router

Update routes/player_route.py:
- Import verify_token from services.auth_service
- Add Depends(verify_token) to POST, PUT, DELETE endpoints
- Keep GET endpoints public
===============================================================================

Task: 3

Create comprehensive test coverage and update API documentation.

Update tests/conftest.py:
- Add settings fixture for test configuration
- Create mock_auth_dependency fixture to override verify_token
- Create authenticated_client fixture using app.dependency_overrides
- Add helper function to generate valid test tokens
- Ensure proper teardown of dependency_overrides

Create tests/test_auth.py:
- Test successful token generation with valid credentials (verify response
structure, token_type, expires_in)
- Test 401 responses for invalid client_id and client_secret
- Test 400 for unsupported grant_type
- Test token decoding and claim validation (sub, exp, scope)

Update tests/test_main.py:
- Test 403 responses for POST, PUT, DELETE /players/ without auth header
- Test successful POST with valid token using dependency override
- Test 403 for expired and malformed tokens
- Verify GET endpoints work without authentication

Update documentation:
- Add /auth/token request to Postman collection with client credentials
- Configure Postman environment variables for access_token
- Update protected requests to use {{access_token}}
- Add authentication section to README with client credentials flow explanation
- Document environment variables and include curl examples

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!