Endpoint
Authentication
No authentication required (this endpoint creates the authentication).Query Parameters
Authorization code provided by GitHub OAuth flow.
CSRF protection state parameter. If prefixed with
"mobile-", the user will be redirected to the mobile app URL.Response
This endpoint returns an HTTP redirect (302 Found) to the frontend application with the access token as a query parameter.Redirect Destinations
Web Client:Error Responses
Error message describing what went wrong.
Error Cases
| Status Code | Description |
|---|---|
| 400 | Missing code parameter in URL |
| 500 | Failed to exchange code for token |
| 500 | Failed to fetch user info from GitHub |
| 500 | Invalid GitHub response (missing login) |
| 500 | Database error during user creation/update |
User Creation Flow
- Exchanges authorization code for GitHub access token
- Fetches user information from GitHub API (
/userendpoint) - Checks if user exists in database by GitHub username
- If new user:
- Creates user record with email, GitHub username, and access token
- If GitHub doesn’t provide email, uses
{username}@users.noreply.github.com
- If existing user:
- Updates the GitHub access token
- Redirects to frontend with access token
Database Schema
The callback creates or updates a User record with:User’s email from GitHub, or generated fallback email.
User’s GitHub login username.
GitHub OAuth access token (used for authentication).
Example Flow
cURL
Environment Variables
| Variable | Default | Description |
|---|---|---|
FRONTEND_URL | http://localhost:5173 | Web application URL for redirect |
MOBILE_URL | Falls back to FRONTEND_URL | Mobile application URL for redirect |
Implementation Details
- Uses GitHub OAuth configuration to exchange code for token
- Fetches user profile from
https://api.github.com/user - Stores access token for subsequent authenticated requests
- Supports both web and mobile client flows via state parameter
- Automatically generates fallback email if GitHub doesn’t provide one
Next Steps
After successful callback, use the provided access token to:- Access protected endpoints via the
Authorization: Bearer {token}header - Retrieve user information from the /me endpoint