Documentation

Authentication System API

SmartCV user authentication system API documentation, including login, registration, session management and other features

Updated: 12/30/2024

SmartCV uses an authentication system based on NextAuth.js, supporting multiple authentication methods including email password login and OAuth social login.

🔐 Authentication Methods

Supported Authentication Methods

  • Email Password Login: Traditional username password authentication
  • Google OAuth: Google account login
  • GitHub OAuth: GitHub account login
  • WeChat Login: WeChat QR code login (planned)

Session Management

SmartCV uses server-side session management, with session information stored in secure HTTP-only cookies.

📋 API Endpoints

1. User Registration

Endpoint: POST /api/register

Description: Create a new user account

Request Body:

{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "Zhang San"
}

Response:

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "Zhang San",
    "emailVerified": false,
    "createdAt": "2024-12-30T10:00:00Z"
  }
}

Error Response:

{
  "error": "Email already registered",
  "code": "EMAIL_ALREADY_EXISTS"
}

2. User Login

Endpoint: POST /api/auth/signin

Description: User login (handled by NextAuth.js)

Request Body:

{
  "email": "user@example.com",
  "password": "securePassword123",
  "callbackUrl": "/dashboard"
}

Response: Redirect to specified page or return session information

3. User Logout

Endpoint: POST /api/auth/signout

Description: User logout, clear session

Request: Requires valid session cookie

Response: Redirect to login page

4. Get Session Information

Endpoint: GET /api/auth/session

Description: Get current user's session information

Response:

{
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "Zhang San",
    "image": "https://avatar.url",
    "subscriptionType": "FREE"
  },
  "expires": "2024-12-31T10:00:00Z"
}

5. Email Verification

Endpoint: POST /api/verify-email

Description: Verify user email

Request Body:

{
  "token": "verification_token_here"
}

Response:

{
  "success": true,
  "message": "Email verification successful"
}

6. Resend Verification Email

Endpoint: POST /api/resend-verification

Description: Resend email verification email

Request Body:

{
  "email": "user@example.com"
}

Response:

{
  "success": true,
  "message": "Verification email sent"
}

7. Forgot Password

Endpoint: POST /api/forgot-password

Description: Send password reset email

Request Body:

{
  "email": "user@example.com"
}

Response:

{
  "success": true,
  "message": "Password reset email sent"
}

8. Reset Password

Endpoint: POST /api/reset-password

Description: Reset password using reset token

Request Body:

{
  "token": "reset_token_here",
  "password": "newSecurePassword123"
}

Response:

{
  "success": true,
  "message": "Password reset successful"
}

🔒 OAuth Login

Google OAuth

Endpoint: GET /api/auth/signin/google

Description: Redirect to Google OAuth authorization page

Parameters:

  • callbackUrl: Callback URL after successful login

GitHub OAuth

Endpoint: GET /api/auth/signin/github

Description: Redirect to GitHub OAuth authorization page

Parameters:

  • callbackUrl: Callback URL after successful login

🛡️ Security Mechanisms

Password Security

  • Encryption: Use bcrypt for password hashing
  • Complexity Requirements: At least 8 characters, including letters and numbers
  • Salt: Each password uses a unique salt

Session Security

  • HTTP-only Cookie: Prevent XSS attacks
  • Secure Cookie: Enabled in HTTPS environment
  • SameSite: Prevent CSRF attacks
  • Expiration Time: Automatically expires after 7 days

Token Security

  • JWT: Signed using HS256 algorithm
  • Short-term Valid: Access token valid for 1 hour
  • Refresh Token: Used to obtain new access tokens

📝 Usage Examples

JavaScript Example

// User registration
async function registerUser(email, password, name) {
  const response = await fetch('/api/register', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email,
      password,
      name
    })
  })
 
  const data = await response.json()
  if (data.success) {
    console.log('Registration successful:', data.data)
  } else {
    console.error('Registration failed:', data.error)
  }
}
 
// Get session information
async function getSession() {
  const response = await fetch('/api/auth/session')
  const session = await response.json()
 
  if (session.user) {
    console.log('Current user:', session.user)
  } else {
    console.log('User not logged in')
  }
}
 
// Using next-auth/react
import { useSession, signIn, signOut } from 'next-auth/react'
 
function AuthComponent() {
  const { data: session, status } = useSession()
 
  if (status === 'loading') return <p>Loading...</p>
 
  if (session) {
    return (
      <>
        <p>Logged in: {session.user.email}</p>
        <button onClick={() => signOut()}>Logout</button>
      </>
    )
  }
 
  return (
    <>
      <p>Not logged in</p>
      <button onClick={() => signIn()}>Login</button>
    </>
  )
}

cURL Example

# User registration
curl -X POST https://smartcv.cc/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123",
    "name": "Zhang San"
  }'
 
# Get session information
curl -X GET https://smartcv.cc/api/auth/session \
  -H "Cookie: next-auth.session-token=your-session-token"
 
# Email verification
curl -X POST https://smartcv.cc/api/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "verification_token_here"}'

❌ Error Handling

Common Error Codes

Error CodeHTTP StatusDescription
EMAIL_ALREADY_EXISTS400Email already registered
INVALID_CREDENTIALS401Invalid login credentials
EMAIL_NOT_VERIFIED403Email not verified
TOKEN_EXPIRED403Token expired
TOKEN_INVALID403Invalid token
USER_NOT_FOUND404User does not exist
WEAK_PASSWORD422Password too weak

Error Response Format

{
  "error": "Email already registered",
  "code": "EMAIL_ALREADY_EXISTS",
  "details": {
    "field": "email",
    "value": "user@example.com"
  }
}

🔧 Development Configuration

Environment Variables

# NextAuth.js configuration
NEXTAUTH_URL=https://smartcv.cc
NEXTAUTH_SECRET=your-secret-key
 
# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
 
# GitHub OAuth
GITHUB_ID=your-github-client-id
GITHUB_SECRET=your-github-client-secret
 
# Email service
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

Callback URL Configuration

Ensure correct callback URLs are configured with OAuth providers:

  • Google: https://smartcv.cc/api/auth/callback/google
  • GitHub: https://smartcv.cc/api/auth/callback/github

Next Steps

📄 Resume Management

Learn how to manage user resumes through API

View Resume API →

👤 User Management

Learn user information and account management related APIs

View User API →

Need help?Contact us for support

Getting StartedUser GuideSupport

Last updated: 12/30/2024 •Suggest improvements