Skip to main content

Authentication API

OAuth2 social login endpoints for the CuliUptime API. CuliUptime uses secure OAuth2 authentication with Google and GitHub.

🔐 OAuth2 Authentication​

Google OAuth2 Login​

Initiate Google OAuth2 authentication flow.

Request:

GET /api/v1/auth/google/login

Example:

# This will redirect to Google's OAuth2 consent screen
curl -X GET https://uptime.culiops.net/api/v1/auth/google/login

Response:

  • Redirects user to Google OAuth2 consent screen
  • After consent, redirects back to /auth/google/callback

Google OAuth2 Callback​

Handle Google OAuth2 callback (automatic).

Request:

GET /api/v1/auth/google/callback?code={code}&state={state}

Note: This endpoint is called automatically by Google after user consent.

GitHub OAuth2 Login​

Initiate GitHub OAuth2 authentication flow.

Request:

GET /api/v1/auth/github/login

Example:

# This will redirect to GitHub's OAuth2 consent screen  
curl -X GET https://uptime.culiops.net/api/v1/auth/github/login

Response:

  • Redirects user to GitHub OAuth2 consent screen
  • After consent, redirects back to /auth/github/callback

GitHub OAuth2 Callback​

Handle GitHub OAuth2 callback (automatic).

Request:

GET /api/v1/auth/github/callback?code={code}&state={state}

Note: This endpoint is called automatically by GitHub after user consent.

🔄 Session Management​

Refresh Access Token​

Refresh the current authenticated session.

Request:

POST /api/v1/auth/refresh

Example:

curl -X POST \
  -b "session_cookie=YOUR_SESSION" \
  https://uptime.culiops.net/api/v1/auth/refresh

Response:

{
  "message": "Token refreshed successfully",
  "expires_at": "2024-01-15T14:30:00Z"
}

Get Current User​

Get information about the currently authenticated user.

Request:

GET /api/v1/auth/user

Example:

curl -X GET \
  -b "session_cookie=YOUR_SESSION" \
  https://uptime.culiops.net/api/v1/auth/user

Response:

{
  "data": {
    "id": 123,
    "email": "[email protected]", 
    "name": "John Doe",
    "provider": "google",
    "avatar_url": "https://...",
    "created_at": "2024-01-01T00:00:00Z",
    "last_login": "2024-01-15T10:00:00Z"
  }
}

Logout​

End the current user session.

Request:

POST /api/v1/auth/logout

Example:

curl -X POST \
  -b "session_cookie=YOUR_SESSION" \
  https://uptime.culiops.net/api/v1/auth/logout

Response:

{
  "message": "Logged out successfully"
}

🛡️ Security Features​

CSRF Protection​

  • State parameter validation prevents CSRF attacks
  • Secure session cookie handling with SameSite protection

Session Security​

  • HTTP-only cookies prevent XSS attacks
  • Secure cookie flags for HTTPS-only transmission
  • Configurable session timeouts

OAuth2 Compliance​

  • Authorization Code flow with PKCE support
  • Proper scope validation and consent handling
  • Secure redirect URI validation

Provider Integration​

  • Google: Uses Google Identity Platform
  • GitHub: Uses GitHub OAuth2 Apps
  • Multi-provider: Users can link multiple accounts

📋 Authentication Flow​

Complete Web Authentication Flow​

  1. User visits dashboard → Sees login options
  2. Clicks "Sign in with Google/GitHub" → Redirects to /auth/{provider}/login
  3. OAuth2 provider consent → User approves application access
  4. Callback handling → Provider redirects to /auth/{provider}/callback
  5. Session creation → CuliUptime creates authenticated session
  6. Dashboard access → User can now access all features and API endpoints

Session-Based API Access​

After authentication, all API calls use session cookies:

# All API endpoints require authenticated session
curl -X GET \
  -b "session_cookie=YOUR_SESSION" \
  https://uptime.culiops.net/api/v1/monitors

The OAuth2 implementation ensures secure, modern authentication following industry best practices for web applications.