use-auth-api

Auth API 프론트엔드 사용 가이드

핵심 원칙

로컬 파일을 읽거나 코드베이스를 탐색하지 말 것. API가 http://localhost:3000에서 실행 중이므로, 필요한 정보는 직접 API를 호출해서 확인한다.

---

프레임워크별 클라이언트 예제

프레임워크	클라이언트	레퍼런스 파일
JavaScript/TypeScript	fetch, axios	references/code-examples.md
NodeJS/Express	fetch, axios (상세)	references/nodejs-client.md
Python/FastAPI	httpx (비동기)	references/fastapi-client.md
Python (일반)	requests (동기)	references/fastapi-client.md

---

기본 정보

• Base URL: http://localhost:3000
• 응답 형식: JSON
• Access Token: Authorization: Bearer {accessToken}
• Refresh Token: Body에 refreshToken 필드로 전달

---

엔드포인트 목록

Method	Path	설명
POST	/auth/register	회원가입
POST	/auth/login	로그인 (토큰 발급)
POST	/auth/logout	로그아웃 (refresh token 폐기)
POST	/auth/refresh	토큰 갱신
POST	/auth/find-account	계정 찾기 (휴대폰 or 이름)
POST	/auth/send-verification	SMS 인증코드 발송
POST	/auth/verify-code	SMS 인증코드 검증
POST	/auth/reset-password-sms	SMS 비밀번호 재설정
POST	/auth/change-password	비밀번호 변경 (인증 필요)
GET	/auth/verify-email/:token	이메일 인증
GET	/auth/sns/:provider	소셜로그인 시작 (Google/Kakao/Naver)
GET	/auth/sns/:provider/callback	소셜로그인 콜백
GET	/auth/me	내 정보 조회 (인증 필요)
PATCH	/auth/me	내 정보 수정 (인증 필요)

---

토큰 구조

Access Token (1시간 유효):

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Refresh Token (7일 유효, Body로 전달):

{ "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

---

코드 예시 (빠른 레퍼런스)

JavaScript/TypeScript (fetch)

// Register
const register = await fetch('http://localhost:3000/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[email protected]', password: 'SecurePass123!', name: 'John' }),
}).then(r => r.json());

// Login
const { accessToken, refreshToken, user } = await fetch('http://localhost:3000/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[email protected]', password: 'SecurePass123!' }),
}).then(r => r.json());

// Use access token
const me = await fetch('http://localhost:3000/auth/me', {
  headers: { Authorization: `Bearer ${accessToken}` },
}).then(r => r.json());

// Refresh token
const { accessToken: newAccess } = await fetch('http://localhost:3000/auth/refresh', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ refreshToken }),
}).then(r => r.json());

// Logout
await fetch('http://localhost:3000/auth/logout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ refreshToken }),
});

Python (httpx async)

import httpx

async with httpx.AsyncClient(base_url="http://localhost:3000") as client:
    # Login
    resp = await client.post("/auth/login", json={
        "email": "[email protected]",
        "password": "SecurePass123!"
    })
    tokens = resp.json()
    access_token = tokens["access_token"]
    refresh_token = tokens["refresh_token"]

    # Get profile
    me = await client.get("/auth/me", headers={
        "Authorization": f"Bearer {access_token}"
    })

    # Refresh
    new_tokens = await client.post("/auth/refresh", json={
        "refresh_token": refresh_token
    })

---

소셜로그인

Google 로그인

1. GET /auth/sns/google
   → { redirectUrl: "https://accounts.google.com/o/oauth2/v2/auth?..." }

2. Redirect browser to redirectUrl (window.location.href = redirectUrl)

3. Google redirects to GET /auth/sns/google/callback?code=xxx

4. Backend exchanges code, then redirects to {FRONTEND_URL}/auth/callback?accessToken=...&refreshToken=...&userId=...

5. Frontend reads tokens from URL query params

Kakao / Naver

동일한 패턴. provider만 kakao 또는 naver로 변경.

---

비밀번호 재설정 (SMS 인증)

비밀번호를 잊어버린 경우, 이메일 대신 SMS 인증을 통해 비밀번호를 재설정합니다.

1. POST /auth/find-account
   Body: { "phone": "01012345678" } or { "name": "John" }
   → { "userId": "...", "maskedPhone": "010****5678" }

2. POST /auth/send-verification
   Body: { "phone": "01012345678" }
   → { "success": true, "expiresIn": 300 }

3. POST /auth/verify-code
   Body: { "phone": "01012345678", "code": "123456" }
   → { "valid": true, "tempToken": "eyJ..." }

4. POST /auth/reset-password-sms
   Headers: { "Authorization": "Bearer {tempToken}" }
   Body: { "newPassword": "NewSecure123!" }
   → { "success": true }

주의: tempToken은 5분内に有効입니다.

---

에러 응답

코드	상황
200	성공
201	사용자 생성 성공
400	검증 오류, 잘못된 토큰
401	인증 실패, 토큰 만료
403	권한 부족
404	사용자 없음
409	이메일 중복
500	서버 오류

---

프레임워크별 상세 예제

각 프레임워크별 상세 예제:

• JavaScript/TypeScript (fetch, axios): references/code-examples.md
• NodeJS/Express (fetch, axios, TypeScript): references/nodejs-client.md
• Python/FastAPI (httpx async): references/fastapi-client.md
• Python (requests 동기): references/fastapi-client.md