PulseGuard supports OAuth authentication through popular providers like Google, GitHub, and Discord. This allows users to authenticate without creating a separate password.

​
Supported Providers

  • Google - google
  • GitHub - github
  • Discord - discord

​
Web Authentication Flow

​
1. Redirect to Provider

Redirect users to the OAuth provider: 
GET /oauth/{provider}
Example: 
https://app.pulseguard.nl/oauth/google

​
2. Handle Callback

After authorization, users are redirected back to: 
GET /oauth/{provider}/callback
The system automatically:
  • Creates new accounts for new users (with free plan)
  • Links existing accounts for returning users
  • Logs users in and redirects to dashboard

​
API Authentication Flow

For headless applications or mobile apps:

​
1. Get Authorization URL

GET /api/oauth/{provider}/auth-url
Response: 
{
  "auth_url": "https://accounts.google.com/oauth/authorize?..."
}

​
2. Handle Callback

After user authorizes, send the authorization code: 
GET /api/oauth/{provider}/callback?code=...&state=...
Response: 
{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "oauth_provider": "google",
    "current_plan": "free"
  },
  "token": "1|abc123...",
  "token_type": "Bearer"
}

​
User Account Linking

  • If a user with the same email already exists, the OAuth account is linked
  • New users are automatically created with the free plan
  • OAuth users have email_verified_at set automatically

​
Example Implementation

​
JavaScript/Frontend

// Get authorization URL
const response = await fetch('/api/oauth/google/auth-url');
const { auth_url } = await response.json();

// Redirect user to OAuth provider
window.location.href = auth_url;

// Handle callback (on your callback page)
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');

if (code) {
  const response = await fetch(`/api/oauth/google/callback${window.location.search}`);
  const { user, token } = await response.json();
  
  // Store token and redirect to app
  localStorage.setItem('api_token', token);
  window.location.href = '/dashboard';
}

​
cURL Example

# Get authorization URL
curl -X GET "https://app.pulseguard.nl/api/oauth/google/auth-url" \\
  -H "Accept: application/json"

# After user authorizes, handle callback
curl -X GET "https://app.pulseguard.nl/api/oauth/google/callback?code=AUTH_CODE&state=STATE" \\
  -H "Accept: application/json"

​
Configuration

OAuth providers must be configured in your environment: 
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=https://app.pulseguard.nl/oauth/google/callback

# GitHub OAuth  
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URI=https://app.pulseguard.nl/oauth/github/callback

# Discord OAuth
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_REDIRECT_URI=https://app.pulseguard.nl/oauth/discord/callback

​
Error Handling

Common error responses: 
{
  "error": "Unsupported OAuth provider"
}

{
  "error": "OAuth authentication failed"
}

​
Security Notes

  • OAuth tokens are stateless for API endpoints
  • Users created via OAuth have verified email addresses
  • Avatar URLs from OAuth providers are stored but not required
  • All OAuth authentications create Laravel Sanctum tokens for API access