docs: enhance REST API authentication guide with alerts and decision matrix

- Added [!IMPORTANT] and [!WARNING] security alerts
- Created decision matrix table for auth method selection
- Added 'Best practices summary' section
- Enhanced procedural clarity and navigation paths
- Consistent code formatting with language identifiers
- All changes follow GitHub docs style guide

Author: lulavcgemini-dev