OAuth Authorize Endpoint - RegardingWork Hub

Overview

The authorization endpoint is used to initiate the OAuth 2.0 authorization code flow. It validates the request parameters, checks if the user is authenticated, and either redirects to login or generates an authorization code.

Endpoint URL

https://hub.regardingwork.com/api/oauth/authorize

Request Parameters

Parameter	Type	Required	Description
`response_type`	string	✅ Yes	Must be `"code"` for authorization code flow
`client_id`	string	❌ No	Client identifier (for tracking purposes)
`redirect_uri`	string	✅ Yes	URL to redirect after authorization (must be from allowed domains)
`scope`	string	❌ No	Space-separated list of requested scopes (e.g., "profile email")
`state`	string	🔒 Recommended	Random value to prevent CSRF attacks
`code_challenge`	string	🔒 Recommended	PKCE code challenge (base64url-encoded SHA256 hash)
`code_challenge_method`	string	❌ No	Must be `"S256"` when using PKCE

Allowed Redirect Domains

The redirect_uri must belong to one of these approved domains:

✅ ce.regardingwork.com
✅ game.regardingwork.com
✅ premium.regardingwork.com
✅ display.regardingwork.com
✅ localhost:3000 (development only)

Response Behavior

User Not Authenticated

HTTP 302 Redirect

Redirects to login page with OAuth parameters preserved:

Location: /login?next=/api/oauth/authorize?client_id=ce&response_type=code&...

User Authenticated

HTTP 302 Redirect

Redirects to callback URL with authorization code:

Location: https://ce.regardingwork.com/callback?code=ABC123&state=xyz

Error Responses

Invalid Response Type

HTTP 400 Bad Request

{
  "error": "unsupported_response_type",
  "error_description": "Only authorization code flow is supported"
}

Invalid Redirect URI

HTTP 302 Redirect

Location: https://invalid-domain.com/callback?error=invalid_request&error_description=Invalid%20redirect_uri%20domain&state=xyz

Example Requests

Complete OAuth Authorization Request

1. Generate PKCE Challenge

// JavaScript example
const codeVerifier = btoa(Array.from(crypto.getRandomValues(new Uint8Array(32)), 
    b => String.fromCharCode(b)).join(''));

const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const digest = await crypto.subtle.digest('SHA-256', data);
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');

2. Construct Authorization URL

const authUrl = 'https://hub.regardingwork.com/api/oauth/authorize?' + new URLSearchParams({
    client_id: 'ce',
    response_type: 'code',
    scope: 'profile email',
    redirect_uri: 'https://ce.regardingwork.com/api/auth/callback',
    state: crypto.randomUUID(),
    code_challenge: codeChallenge,
    code_challenge_method: 'S256'
});

// Redirect user to authorization URL
window.location.href = authUrl;

3. Full Authorization URL Example

https://hub.regardingwork.com/api/oauth/authorize?client_id=ce&response_type=code&scope=profile+email&redirect_uri=https%3A%2F%2Fce.regardingwork.com%2Fapi%2Fauth%2Fcallback&state=550e8400-e29b-41d4-a716-446655440000&code_challenge=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&code_challenge_method=S256

Authorization Flow

1. Client App
   │
   ├─ Generate PKCE challenge
   ├─ Redirect user to /api/oauth/authorize
   │
   ▼
2. RegardingWork Hub
   │
   ├─ Validate parameters
   ├─ Check user authentication
   │
   ├─ If NOT authenticated:
   │  └─ Redirect to /login with OAuth params
   │
   ├─ If authenticated:
   │  ├─ Generate authorization code
   │  ├─ Store code details in session
   │  └─ Redirect to callback with code
   │
   ▼
3. Client App Callback
   │
   ├─ Extract authorization code from URL
   ├─ Validate state parameter
   └─ Exchange code for tokens at /api/oauth/token