Initiate GitHub OAuth
Behavior
- Generates a random CSRF state token (32 bytes, URL-safe)
- Stores the state in the database with a 10-minute expiration
- Cleans up expired OAuth states
- Redirects to GitHub OAuth with required scopes
OAuth Scopes
repo- Full control of private repositoriesread:user- Read user profile datauser:email- Access user email addressesread:org- Read organization membership
Response
Redirects to
https://github.com/login/oauth/authorize with:client_id- Application’s GitHub client IDscope- Required OAuth scopesstate- CSRF protection token
GitHub OAuth Callback
Query Parameters
Authorization code from GitHub
CSRF state token that matches the one stored in the database
Behavior
- Validates the state token against the database
- Exchanges the authorization code for a GitHub access token
- Fetches the user’s GitHub profile
- Creates or updates the user in the database
- Encrypts and stores the GitHub access token
- Generates a JWT access token
- Sets the JWT as an httpOnly cookie
- Redirects to the frontend dashboard
Response
Redirects to
{FRONTEND_URL}/dashboard with:access_tokencookie (httpOnly, secure in production)- Cookie max age:
ACCESS_TOKEN_EXPIRE_MINUTES * 60seconds - SameSite:
none(production) orlax(development)
Error Responses
Invalid or expired OAuth state - The state token is missing, invalid, or expired
Failed to exchange GitHub code - GitHub token exchange failed
Failed to fetch GitHub user - Unable to retrieve GitHub user profile
Reconnect GitHub Account
Authentication
access_token - JWT token in httpOnly cookieBehavior
- Decrypts the stored GitHub access token
- Revokes the token with GitHub
- Deletes the JWT cookie
- Generates a new CSRF state token
- Redirects to GitHub OAuth authorization page
Response
Redirects to GitHub OAuth with:
- Deleted
access_tokencookie - New OAuth flow initiated
Not authenticated - Missing or invalid JWT token
Token revocation failures are logged but don’t prevent the reconnection flow from continuing.