[stevemessick]

Summary

Validates credential formats upfront during authentication and prints actionable error messages when new KGAT_ API access tokens and legacy kaggle.json credentials are mixed up or malformed:

• KGAT_ token placed in kaggle.json or KAGGLE_KEY:
  • KaggleApi.read_config_file() detects raw KGAT_ tokens or malformed JSON in ~/.kaggle/kaggle.json instead of silently ignoring parse errors, and guides the user/agent to ~/.kaggle/access_token or KAGGLE_API_TOKEN.
  • KaggleApi._authenticate_with_legacy_apikey() rejects KGAT_ / KGRT_ tokens configured in KAGGLE_KEY or kaggle.json (key, token, api_token, apiToken), removes the invalid key from config_values, and prints clear instructions.
• Legacy credentials or malformed tokens placed in ~/.kaggle/access_token or KAGGLE_API_TOKEN:
  • KaggleApi._validate_access_token_format() fails fast before calling _introspect_token() when access_token or KAGGLE_API_TOKEN contains legacy JSON credentials ({"username": "...", "key": "..."}), a JSON-wrapped KGAT_ token, a bare 32-character hex legacy API key without KGAT_, an OAuth refresh token (KGRT_...), quotes/KEY=VALUE syntax, or a truncated/malformed KGAT_ token.
  • KaggleApi._introspect_token() also catches HTTP 401 responses alongside (400, 403, 404) so invalid or expired bearer tokens do not raise an unhandled HTTPError.

Test Plan

• Added 14 unit tests in tests/unit/test_authenticate.py covering all credential format mismatches as well as valid KGAT_ and OAuth bearer tokens.
• Verified the full unit test suite (1450 passed) and black / mypy.

[rosbo]

Do we already have tests that check the happy path? (i.e. valid token or kaggle.json format).

[stevemessick]

Yes! We have:

• test_valid_kgat_token_in_access_token_succeeds (for valid KGAT_<32-hex> tokens)
• test_oauth_bearer_token_in_access_token_succeeds (for valid OAuth bearer tokens)
• test_environment_variables (for legacy KAGGLE_USERNAME / KAGGLE_KEY env vars)
• Added test_valid_kaggle_json_file_succeeds in the latest commit to also cover reading a valid kaggle.json file from disk.

[stevemessick]

Thanks for the quick review!