Skip to content

JWT Security

This guide documents the current JWT authentication model used by the Tracker REST API. The implementation lives in app/core/security.py.

What Is Enforced

  • HMAC-SHA256 signatures are required
  • The configured algorithm is the only accepted algorithm
  • Tokens must include the expected issuer and audience
  • Expiration, issued-at, and JWT ID claims are validated
  • Unverified JWT operations are not used

Token Shape

Access tokens include the standard claims needed for validation:

{
  "exp": 1234567890,
  "iat": 1234567800,
  "sub": "user_id",
  "iss": "tracker-api",
  "aud": "tracker-clients",
  "jti": "unique-token-id",
  "token_type": "access"
}

Configuration

Relevant settings are:

SECRET_KEY = "your-strong-secret-key-here"
ALGORITHM = "HS256"
JWT_ISSUER = "tracker-api"
JWT_AUDIENCE = "tracker-clients"
ACCESS_TOKEN_EXPIRE_MINUTES = 30
REFRESH_TOKEN_EXPIRE_DAYS = 7

Security Testing

Run the JWT security tests with:

./run_tests_with_coverage.sh tests/core/test_security.py

The tests cover token creation, signature verification, claim validation, and error handling.

Troubleshooting

  • Invalid token errors usually mean the signature, issuer, audience, or expiration check failed
  • If tokens are being rejected unexpectedly, confirm SECRET_KEY and ALGORITHM match the runtime
  • If you are debugging locally, set ENVIRONMENT=development for more detailed logging