API 인증 쿠키 문제를 빨리 좁히는 법

API 인증 문제는 화면만 보면 놓치는 값이 많다. 실제로 서버로 어떤 요청이 가고 있는지, 그리고 어떤 응답이 돌아오는지를 직접 확인해야 한다.

문제 재현할 때 환경 정보 함께 기록하기

로컬 개발 환경에서는 정상이었는데 배포 서버에서 인증이 안 된다면, 단순히 "인증이 안 된다"고 적으면 안 된다. 어떤 브라우저에서, 어떤 디바이스에서, 어떤 네트워크 환경에서 발생했는지 함께 남겨둔다. 같은 증상이 다시 나타날 때 이 정보가 첫 단서가 된다.

쿠키와 헤더를 함께 확인하기

로그인 요청을 보내면 서버에서 Set-Cookie 헤더로 쿠키를 돌려준다. 그 다음 요청에서 브라우저가 자동으로 그 쿠키를 Cookie 헤더에 붙여 보내는데, 이 과정이 제대로 되고 있는지 확인해야 한다.

# curl로 쿠키 추출 후 다음 요청에 포함시키기
curl -i -c cookies.txt 'https://api.example.com/login' \
  -d '{"username":"test","password":"pass"}'

curl -i -b cookies.txt 'https://api.example.com/user/profile'

응답 바디와 상태 코드를 함께 기록하기

401 응답이 나오면 보통 인증 실패다. 하지만 같은 401이어도 이유가 다를 수 있다. 쿠키 만료, 토큰 서명 오류, 권한 부족 등. 응답 바디에 에러 메시지가 있으면 그것을 정확히 복사해서 로그에 남긴다. 나중에 같은 문제를 봤을 때 이 메시지가 재발인지 새로운 문제인지 판단하게 해준다.

로컬과 서버의 차이를 항상 의심하기

로컬에서 테스트할 때는 HTTPS를 안 쓰거나 SameSite 정책을 느슨하게 해놨을 수 있다. 서버 환경에서는 엄격한 정책이 적용되면서 쿠키가 제대로 전송되지 않을 수 있다. 배포 전에 로컬에서라도 운영 환경과 동일한 HTTPS, 도메인, 쿠키 정책을 적용해 한 번 테스트해보자.