Account API

The Account API manages user account information through Better Auth integration. Handles linked social accounts (Google OAuth) and active session management for security and account control.

Account Details Model

accounts: Array of linked social accounts
sessions: Array of active user sessions

id: Account link identifier (string)
providerId: OAuth provider identifier (string: "google")
accountId: Provider's account ID (string)
createdAt: Account link creation date (string, ISO datetime)
accessToken: Has access token (boolean)
refreshToken: Has refresh token (boolean)

Session Model

id: Session identifier (string)
createdAt: Session creation time (string, ISO datetime)
updatedAt: Last session activity (string, ISO datetime)
expiresAt: Session expiration time (string, ISO datetime)
ipAddress: Session IP address (string)
userAgent: Browser/client information (string)

Endpoints

All account endpoints require authentication and are scoped to the authenticated user.

Get Account Details

Retrieve current user's linked accounts and active sessions.

GET /api/account/details

Response (200)

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "account_abc123",
        "providerId": "google",
        "accountId": "123456789012345",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "accessToken": true,
        "refreshToken": true
      }
    ],
    "sessions": [
      {
        "id": "session_def456",
        "createdAt": "2024-01-15T08:00:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "expiresAt": "2024-02-15T08:00:00.000Z",
        "ipAddress": "192.168.1.100",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      },
      {
        "id": "session_ghi789",
        "createdAt": "2024-01-14T12:00:00.000Z",
        "updatedAt": "2024-01-15T09:45:00.000Z",
        "expiresAt": "2024-02-14T12:00:00.000Z",
        "ipAddress": "10.0.0.50",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
      }
    ]
  },
  "message": "Account details retrieved successfully"
}

Errors:

401: Authentication required

Remove a linked social account (Google OAuth) from the user's account.

POST /api/account/unlink
Content-Type: application/json

{
  "accountId": "account_abc123"
}

Request Body Parameters

accountId: Account link ID to unlink (required)

Response (200)

{
  "success": true,
  "message": "Account unlinked successfully"
}

Errors:

400: Invalid account ID or request data
401: Authentication required
404: Account not found

Revoke Session

Revoke a specific user session (logout from specific device/browser).

POST /api/account/revoke-session
Content-Type: application/json

{
  "sessionId": "session_ghi789"
}

Request Body Parameters

sessionId: Session ID to revoke (required)

Response (200)

{
  "success": true,
  "message": "Session revoked successfully"
}

Errors:

400: Invalid session ID or request data
401: Authentication required
404: Session not found

Account Security

Session Management

Multiple Sessions: Users can have active sessions on multiple devices
Session Tracking: Each session tracks IP address, user agent, and activity times
Session Expiration: Sessions automatically expire based on Better Auth configuration
Manual Revocation: Users can manually revoke specific sessions for security

Google OAuth: Primary social login provider with calendar permissions
Account Information: Securely stores provider account IDs and token status
Token Management: Access and refresh tokens managed by Better Auth
Secure Unlinking: Users can unlink social accounts while maintaining account access

Integration with Better Auth

The Account API integrates with Better Auth for:

Authentication Flow

// User authentication is handled by Better Auth
// Account management happens after successful authentication

// Get account details
const accountResponse = await fetch('/api/account/details', {
  headers: { 'Authorization': 'Bearer ' + sessionToken }
});

// Unlink Google account
await fetch('/api/account/unlink', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ accountId: 'account_123' })
});

// Revoke session (logout from specific device)
await fetch('/api/account/revoke-session', {
  method: 'POST', 
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ sessionId: 'session_456' })
});

Security Considerations

Session Isolation: Users can only access their own sessions and linked accounts
Token Security: Access and refresh tokens are securely managed by Better Auth
Audit Trail: Session creation and revocation events are logged
Protection: All endpoints require valid authentication tokens

Google Calendar Integration

OAuth Permissions

When linking Google accounts, the system requests:

Calendar Read Access: https://www.googleapis.com/auth/calendar.readonly
Profile Information: Basic profile data for account identification
Email Access: Email address for account linking and verification

Calendar Sync Features

Event Import: Automatic calendar event synchronization
Syllabus Integration: Calendar events created from syllabus processing
Academic Schedule: Integration with course schedules and deadlines

Data Privacy

Account Data

Minimal Storage: Only essential account linking information is stored
Token Security: OAuth tokens are encrypted and securely managed
User Control: Users maintain full control over linked accounts and active sessions

Session Privacy

Limited Information: Session data includes only necessary security information
No Content Tracking: Session management doesn't track user content or activities
Secure Cleanup: Revoked sessions are immediately invalidated

Error Handling

Common Error Scenarios

Invalid Account ID: Attempting to unlink non-existent or already unlinked accounts
Invalid Session ID: Attempting to revoke non-existent or already expired sessions
Unauthorized Access: Accessing account endpoints without valid authentication
Missing Parameters: Request body missing required fields

Error Response Format

{
  "success": false,
  "error": "Account not found",
  "code": "ACCOUNT_NOT_FOUND"
}

Account management integrates with:

Authentication API: Better Auth signin/signup flows
Calendar API: Google Calendar integration and event synchronization
Security: Session-based authentication and authorization
Privacy: User data protection and account control

Account API

On this page