Skip to main content

​
Initiate GitHub Login

curl -X GET 'http://localhost:8000/auth/github'
Redirects the user to GitHub OAuth authorization page. Method: GET /auth/github Authentication: None required

​
Flow

  1. Generates a cryptographically secure random state token
  2. Stores state in database with 10-minute expiration
  3. Redirects to GitHub with client ID, scopes, and state

​
Redirect URL

https://github.com/login/oauth/authorize?client_id=<CLIENT_ID>&scope=repo,read:user,user:email&state=<STATE>

​
GitHub OAuth Callback

Method: GET /auth/github/callback Authentication: None required (validates state parameter)
​
code
string
required
Authorization code from GitHub
​
state
string
required
CSRF protection token (must match server-stored state)

​
Response

Redirects to {FRONTEND_URL}/dashboard with JWT cookie set. 
Set-Cookie: access_token=<JWT>; HttpOnly; Secure; SameSite=None; Max-Age=86400; Path=/

​
Error Responses

​
detail
string
Error message
  • 400: Invalid or expired OAuth state
  • 400: Failed to exchange GitHub code
  • 400: Failed to fetch GitHub user

​
Get Current User

curl -X GET 'http://localhost:8000/auth/me' \
  --cookie 'access_token=<your_jwt>'
Method: GET /auth/me Authentication: Required (JWT cookie)

​
Response

​
id
integer
required
Internal user ID
​
github_id
integer
required
GitHub user ID
​
github_username
string
required
GitHub username
​
name
string
User’s display name from GitHub
​
email
string
Primary email address
​
avatar_url
string
GitHub avatar URL
​
created_at
string
required
ISO 8601 timestamp of first login

​
Example Response

{
  "id": 42,
  "github_id": 12345678,
  "github_username": "octocat",
  "name": "The Octocat",
  "email": "[email protected]",
  "avatar_url": "https://avatars.githubusercontent.com/u/12345678",
  "created_at": "2025-01-15T08:30:00.000000"
}

​
Logout

curl -X POST 'http://localhost:8000/auth/logout' \
  --cookie 'access_token=<your_jwt>'
Method: POST /auth/logout Authentication: None required (clears cookie regardless)

​
Response

{
  "message": "Logged out"
}
The access_token cookie is deleted from the client.

​
Notes

  • Does not revoke the GitHub access token (user can manually revoke in GitHub settings)
  • Clears the JWT cookie only; does not delete user from database

Build docs developers (and LLMs) love

Get started for freeTalk to us