Add OAuth authentication support for Claude Code integration

[Umaaz]

Overview

This merge request introduces OAuth as the recommended authentication method for the Claude Code integration, providing a more secure and user-friendly alternative to API token authentication. The changes streamline the setup process for users by enabling browser-based authentication and automatic session management. Existing API token support is maintained for backward compatibility and for use cases like CI/CD pipelines.

The documentation has been significantly restructured to clearly present both OAuth and API token authentication methods, with detailed instructions and a comparison to help users choose the appropriate approach.

Technical Details

• Files Changed: docs/integrations/claude-code.md
• Change Type: Modification
• Context:
  • Implemented the OAuth flow as the primary authentication method, with the endpoint configured at https://api.opentrace.ai/mcp/v1/oauth.
  • OAuth sessions now persist across Claude Code sessions, improving the user experience.
  • Restructured the claude-code.md documentation to create two distinct guides:
    • Method A: OAuth Flow (Recommended for personal use)
    • Method B: API Token (For CI/CD, service accounts, etc.)
  • Added a comparison table to help users decide which authentication method best suits their needs.
  • Updated prerequisites to reflect that an API token is no longer required for the primary setup flow.
  • Enhanced the troubleshooting section with guidance for common OAuth-specific issues (e.g., browser not opening, session expiration).
  • Maintained backward compatibility by supporting both project-level (.mcp.json) and global (~/.claude/settings.json) configurations.

Review Summary

• Key Findings: The review process was smooth, and no major issues were identified.
• Approval Status: Approved.

Impact Assessment

• Security: This change improves the overall security of the integration. By promoting OAuth, we reduce the risks associated with manually handling and storing API tokens, as authentication is handled through a secure, standard browser flow.
• Performance: No negative performance impact is expected. The persistent OAuth sessions are expected to improve user workflow by reducing the need for repeated authentication.
• Maintainability: The restructured documentation is clearer and more comprehensive, which will make it easier for users to set up the integration and for developers to maintain it in the future. The clear separation of authentication methods improves the long-term scalability of the documentation.

---

Attached by run j-50d25199-cbae-4072-9963-25320c05c5ac

[github-actions]

📚 Documentation Preview

Preview deployed to: https://opentrace.github.io/docs/preview/11-merge/

[opentrace]

Approved

[opentrace]

The merge request is well-structured and significantly improves the user experience by adding OAuth support, which is a more secure and user-friendly authentication method. The documentation changes are comprehensive, clear, and maintain backward compatibility. The addition of detailed troubleshooting and verification steps is also a great enhancement.

---

Attached by run j-50d25199-cbae-4072-9963-25320c05c5ac