Authentication Guide
Complete documentation for user authentication, security protocols, and developer integration on ConnectHub.
Overview
ConnectHub implements a multi-layered authentication system designed to balance security, usability, and developer flexibility. Our platform supports OAuth 2.0, OpenID Connect, multi-factor authentication (MFA), and robust session management.
Account Creation
Users can register via email/password, or through supported OAuth providers (Google, Apple, GitHub, X). New accounts require email verification before full access is granted.
Registration Endpoint
{ "email": "user@example.com", "password": "SecurePass123!", "username": "connectdev", "terms_accepted": true }
Upon successful registration, the system returns a 201 Created status and sends a verification token to the provided email address.
Login Flow
Authentication tokens are issued as short-lived JWTs (15 minutes) paired with long-lived, secure, HttpOnly refresh tokens (30 days). This architecture minimizes exposure while maintaining seamless user experience.
Credentials Submission
User submits credentials via the secure login endpoint. Rate limiting is enforced at 5 attempts per minute per IP/account.
Token Issuance
Upon validation, the server returns an access token, refresh token, and token expiration timestamp.
Session Establishment
The client stores the refresh token in a secure, sameSite=strict cookie and manages the access token in memory.
Two-Factor Authentication (2FA)
ConnectHub supports TOTP (RFC 6238) and SMS-based 2FA. TOTP is recommended for enhanced security. Users can generate backup codes during setup for account recovery.
TOTP Setup Payload
{ "secret": "JBSWY3DPEHPK3PXP", "qr_uri": "otpauth://totp/ConnectHub:user@example.com?secret=...", "backup_codes": ["89123456", "45123789", ...] }
Password Recovery
The password reset flow uses time-limited, single-use tokens delivered via email. Tokens expire after 60 minutes or after one successful use.
| Endpoint | Method | Description |
|---|---|---|
/auth/forgot-password | POST | Requests reset token |
/auth/reset-password | PUT | Applies new password with token |
/auth/verify-recovery | GET | Validates token status |
Session Management
ConnectHub maintains an active session registry. Users can view, monitor, and revoke sessions from any device via the account settings dashboard.
- Device Fingerprinting: Tracks OS, browser, IP range, and hardware signatures.
- Idle Timeout: Sessions expire after 1 hour of inactivity on web, 24 hours on mobile.
- Force Logout: Revoking a session immediately invalidates the associated refresh token server-side.
API Authentication
Developers integrating with ConnectHub should use OAuth 2.0 PKCE flow for public clients or standard Authorization Code flow for confidential clients.
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... x-ch-api-key: sk_live_8xK9mP2vQ4wL7zN5
Scopes must be explicitly requested and granted. Common scopes include read:profile, write:posts, and read:analytics.
Security Best Practices
- Always enable 2FA on creator and admin accounts
- Use passkeys/WebAuthn where supported
- Rotate API keys quarterly and audit access logs
- Never log or store raw passwords or tokens
- Implement adaptive authentication for risky locations
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
401 Unauthorized | Expired or invalid access token | Refresh token or re-authenticate |
403 Forbidden | Insufficient scope or account restriction | Check app permissions or contact support |
| 2FA code rejected | Device clock desync (>30s) | Sync system time or use backup codes |
| Login rate limited | Too many failed attempts | Wait 15 mins or verify via email link |
For persistent authentication issues, generate a diagnostic report via Settings > Security > Export Auth Logs and submit it to our developer support portal.