Skip to main content

API Authentication

CuliUptime uses OAuth2 social login for secure authentication. API access is session-based through the web dashboard.

🔐 Authentication Method​

OAuth2 Social Login​

CuliUptime supports secure login through:

  • Google OAuth2 - Sign in with your Google account
  • GitHub OAuth2 - Sign in with your GitHub account

Session-Based API Access​

# API calls require authenticated session cookies
curl -b "session_cookie=YOUR_SESSION" \
     https://uptime.culiops.net/api/v1/monitors

🚀 Getting Started​

1. Web Dashboard Login​

  1. Navigate to your CuliUptime dashboard
  2. Click "Sign in with Google" or "Sign in with GitHub"
  3. Complete the OAuth2 authorization process
  4. You'll be redirected back with an authenticated session

2. API Access Flow​

# 1. Initiate OAuth2 login (redirects to provider)
curl https://uptime.culiops.net/api/v1/auth/google/login

# 2. After successful OAuth2, your session is authenticated
# 3. Make API calls with session cookies
curl -X GET \
  -b "session_cookie=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  https://uptime.culiops.net/api/v1/monitors

🔄 Token Management​

Access Token Refresh​

Sessions can be refreshed using the refresh endpoint:

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

Session Information​

Get current user information:

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

🛡️ Security Features​

OAuth2 Implementation​

  • Secure Authorization Code Flow with PKCE protection
  • State Parameter validation to prevent CSRF attacks
  • Nonce Validation for additional security
  • HTTPS Enforcement for all authentication flows

Session Security​

  • HTTP-Only Cookies to prevent XSS attacks
  • SameSite Cookie Protection against CSRF
  • Secure Flag for HTTPS-only transmission
  • Session Expiration with configurable timeouts

Provider-Specific Features​

  • Google OAuth2: Supports email and profile scopes
  • GitHub OAuth2: Repository and organization access (if needed)
  • Multi-Provider: Users can link multiple OAuth2 providers

🚫 Logout​

End Session​

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

📋 Best Practices​

Security Guidelines​

  1. Always use HTTPS for authentication flows
  2. Validate redirect URLs to prevent open redirect attacks
  3. Store session cookies securely in your applications
  4. Implement proper session timeout handling
  5. Monitor authentication logs for suspicious activity

Error Handling​

# Handle authentication errors gracefully
if ! curl -f -b "session_cookie=$SESSION" /api/v1/auth/user; then
    # Redirect to login flow
    curl https://uptime.culiops.net/api/v1/auth/google/login
fi

🔍 Troubleshooting​

Common Issues​

  • Session Expired: Use refresh endpoint or re-authenticate
  • CORS Errors: Ensure proper origin configuration
  • Redirect Loops: Check callback URL configuration
  • Provider Errors: Verify OAuth2 app settings

Authentication States​

  • Unauthenticated: Redirect to OAuth2 login
  • Authenticated: Session valid, API access granted
  • Expired: Session expired, refresh or re-authenticate required

The OAuth2 implementation ensures secure, modern authentication while maintaining ease of use for API access through the web dashboard.