Allow to use bearer header in all our API

[konard]

Also keep query parameters support for some time.

Check it is more secure to use headers instead of query parameters or this is just common practice, not to surprise users.

[konard]

✅ Implementation Complete

I've completed the implementation for allowing Bearer token authentication in all our API endpoints. Here's what has been delivered:

📦 Deliverables

1. Documentation (master-plan repository)

• BEARER_TOKEN_SOLUTION.md - Comprehensive solution document including:

  • Detailed security analysis (OAuth 2.0 RFC 6750 compliance)
  • Architecture diagrams
  • Migration guide for API consumers
  • Timeline and testing strategy

• IMPLEMENTATION_PLAN.md - Technical implementation details:

  • Files modified
  • Code patterns
  • Testing checklist
  • Deployment steps

2. Implementation (api-gateway repository)

• Pull Request: deep-assistant/api-gateway#4
• Changes:
  • Added getMasterTokenFromRequest() to TokensService
  • Updated 10 endpoints across 5 controllers
  • Full backward compatibility maintained
  • Deprecation warnings for query parameter usage

🔍 Security Answer

"Check it is more secure to use headers instead of query parameters or this is just common practice, not to surprise users."

Answer: Both. It's common practice because it's actually more secure.

Specific Security Improvements:

1. Prevents Log Exposure: Query parameters appear in web server logs, browser history, proxy logs, and Referer headers
2. OAuth 2.0 Compliance: RFC 6750 explicitly states query parameters "SHOULD NOT be used" for access tokens
3. Audit Requirements: Required for SOC 2, ISO 27001 compliance
4. Attack Surface Reduction: Headers are less likely to be accidentally exposed through screenshots, URL sharing, etc.

Even with HTTPS (which both methods require), headers provide defense-in-depth by avoiding URL-based exposure vectors.

✅ Backward Compatibility

No breaking changes! Both methods work:

New Way (Recommended):

curl -H "Authorization: Bearer ${MASTER_TOKEN}" \
  "https://api.example.com/token?userId=123"

Old Way (Deprecated, Still Works):

curl "https://api.example.com/token?userId=123&masterToken=${MASTER_TOKEN}"
# ⚠️ Logs deprecation warning

📋 Next Steps

1. Review: Review and approve api-gateway#4
2. Merge: Merge the implementation PR
3. Deploy: Deploy api-gateway to production
4. Notify: Update telegram-bot and other API consumers
5. Monitor: Track deprecation warnings over 6-12 months
6. Cleanup: Remove query parameter support in v2.0.0

🔗 Pull Requests

• Implementation: Add Bearer token authentication support for all API endpoints deep-assistant/api-gateway#4
• Documentation: Allow to use bearer header in all our API #39

Ready for review! 🚀