184

Implementation Plan: User Profile Endpoint

Issue: #184 - What’s your name?

Summary

Add a user profile API endpoint that returns the authenticated user’s information, specifically their name and basic profile data. This addresses the question “What’s your name?” by providing a way for the application to retrieve and display the current user’s identity information. The implementation will leverage the existing Clerk authentication system to extract user details from the JWT token.

Approach

1. Create new API route at api/src/routes/user_profile.py

   • Add handler for GET /api/user/profile endpoint
   • Extract user information from Clerk JWT token (name, email, user_id)
   • Return structured user profile response

2. Update OpenAPI specification in api/openapi.yaml

   • Add new /api/user/profile path definition
   • Define UserProfile response schema
   • Include authentication requirements

3. Register route in api/src/index.py

   • Import new user profile handler
   • Add route mapping for /api/user/profile

4. Add frontend API client method in packages/web/src/api/client.ts

   • Create getUserProfile() method
   • Add TypeScript interface for user profile response

5. Update authentication middleware (if needed)

   • Ensure user profile extraction from JWT includes name fields
   • Verify existing verify_user_token handles name claims correctly

6. Add basic tests

   • Unit test for user profile endpoint
   • Ensure proper error handling for unauthenticated requests

Layers

backend, api, frontend

• Backend: New Python route handler and authentication logic
• API: New endpoint definition and OpenAPI spec updates
• Frontend: API client method to consume the new endpoint

Risks

1. JWT token configuration - Clerk JWT template may not include name claims by default, requiring configuration changes
2. Name field variations - Different authentication providers may use different claim names (firstName/lastName vs name vs displayName)
3. Privacy considerations - Need to ensure we only return necessary user information, not sensitive data
4. Rate limiting - Profile endpoint could be called frequently, may need caching or rate limits

Open Questions

1. What specific user information should be returned? (full name, email, avatar, etc.)
2. Should we cache user profile data or fetch fresh from Clerk on each request?
3. Do we need to handle different name formats from various OAuth providers?
4. Should this endpoint be public (for displaying user info) or require special permissions?
5. Is there a preferred location in the UI to eventually display the user’s name?

Notes

• Existing /api/companies endpoint shows the pattern for JWT authentication and email extraction
• Frontend already has Clerk SignedIn/SignedOut components for auth state management
• Consider this as foundation for future user profile features (settings, preferences, etc.)