Skip to main content

​
Authentication API

All authentication endpoints are under /api/v1/auth/ and are rate-limited to 20 requests per minute per IP.

​
OAuth Login

​
GET /api/v1/auth/google

Initiates Google OAuth 2.0 login flow. Redirects the browser to Google’s authorization page. 
# Redirect — open in browser
GET /api/v1/auth/google
Callback: GET /api/v1/auth/google/callback — handled automatically.

​
GET /api/v1/auth/github

Initiates GitHub OAuth 2.0 login flow. Redirects to GitHub’s authorization page. 
GET /api/v1/auth/github
Callback: GET /api/v1/auth/github/callback — handled automatically.

​
GET /api/v1/auth/steam/login

Initiates Steam OpenID login for unauthenticated users. Redirects to Steam’s login page. 
GET /api/v1/auth/steam/login
Callback: GET /api/v1/auth/steam/login/callback — handled automatically.

​
GET /api/v1/auth/steam

Links a Steam account to an authenticated user. Requires an active session. 
GET /api/v1/auth/steam
This endpoint requires authentication. The user must already be logged in via another provider.
Callback: GET /api/v1/auth/steam/callback — handled automatically.

​
POST /api/v1/auth/magic/request

Request a magic link email for passwordless login. Request Body: 
{
  "email": "user@example.com"
}
Response: 
{
  "message": "if an account exists with that email, a login link has been sent"
}
The response is always the same regardless of whether the email exists. This prevents email enumeration.

​
GET /api/v1/auth/magic/verify

Verify a magic link token and create a session. Called when the user clicks the link in their email. Query Parameters:
ParameterTypeDescription
tokenstringThe magic link token
Behavior: Validates the token, creates/matches the user, starts a session, and redirects to the frontend.

​
Session Management

​
GET /api/v1/auth/me

Returns the current authenticated user, or null if not authenticated. 
curl http://localhost:8080/api/v1/auth/me -b cookies.txt

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "avatar_url": "https://lh3.googleusercontent.com/...",
    "role": "user",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

​
POST /api/v1/auth/logout

Destroys the current session. Requires authentication and CSRF token. 
curl -X POST http://localhost:8080/api/v1/auth/logout \
  -b cookies.txt \
  -H "X-CSRF-Token: {token}"
Response: 
{
  "message": "logged out"
}

​
GET /api/v1/auth/providers

Lists the authentication providers linked to the current user’s account. Requires: Authentication 
curl http://localhost:8080/api/v1/auth/providers -b cookies.txt
Response: 
{
  "providers": [
    {
      "provider": "google",
      "linked_at": "2025-01-15T10:30:00Z"
    },
    {
      "provider": "steam",
      "linked_at": "2025-01-20T14:00:00Z"
    }
  ]
}

​
GET /api/v1/auth/csrf

Returns a CSRF token for the current session. 
curl http://localhost:8080/api/v1/auth/csrf -b cookies.txt
Response: 
{
  "csrf_token": "abc123..."
}