토큰 하나만 헤더에 넣으면 되는 API가 있는가 하면, 요청을 보낼 때마다 그 요청 내용으로 서명을 계산해 붙여야 하는 API도 있습니다. 광고·정산 데이터를 다루는 플랫폼일수록 후자가 많습니다. 데이터 자체가 민감하니 인증을 더 강하게 겁니다. 이런 서명 기반 API를 파이프라인에 붙일 때 클라이언트를 어떻게 설계했는지 정리합니다.
서명은 요청마다 새로 계산된다
서명 인증의 핵심은 인증 정보가 한 번 발급되고 끝나는 토큰이 아니라, 매 요청마다 그 순간의 정보로 새로 만들어진다는 점입니다. 요청 시각과 HTTP 메서드, 호출 경로를 정해진 순서로 이어 붙여 하나의 메시지를 만들고 비밀 키로 HMAC-SHA256 해시를 계산한 뒤 그 결과를 인코딩해 서명 헤더에 담습니다. 여기에 발급받은 API 키와 계정 식별자, 그리고 방금 쓴 시각을 함께 헤더로 보냅니다.
이 구조 덕에 서명은 짧은 시간만 유효하고 요청을 가로채도 다른 경로나 메서드에 재사용할 수 없습니다. 반대로 구현하는 입장에서는 실수의 여지가 여기저기 있습니다. 메시지를 잇는 순서가 규격과 조금만 달라도, 시각의 단위가 초와 밀리초로 어긋나기만 해도 서명은 통째로 틀립니다. 그래서 서명 생성은 다른 로직과 섞지 않고 입력만 받아 문자열을 돌려주는 순수 함수로 떼어 두는 편이 검증하기 좋습니다.
클라이언트가 서명을 감춘다
파이프라인의 나머지 코드가 매 호출마다 서명을 신경 쓰게 하면 실수가 퍼집니다. 그래서 서명 계산과 헤더 구성은 API 클라이언트 안쪽에 감추고 바깥에서는 평범하게 경로와 본문만 넘겨 호출하도록 했습니다. 클라이언트의 요청 메서드가 호출되는 순간 그 요청에 맞는 서명을 만들어 붙이므로, 이 API가 서명 인증이라는 사실을 상위 로직은 몰라도 됩니다.
재미있는 함정 하나는 다운로드 링크에도 인증이 필요하다는 점이었습니다. 리포트를 받아가라며 준 URL조차 그냥 접속하면 거부되고 그 경로에 맞는 서명을 다시 만들어 헤더로 보내야 파일을 내줍니다. 그래서 클라이언트에 일반 호출뿐 아니라 인증이 걸린 다운로드 전용 경로도 함께 두었습니다.
재시도와 요청 제한을 클라이언트가 흡수한다
외부 API는 언제든 일시적으로 흔들립니다. 서버가 잠깐 5xx를 돌려주거나, 너무 자주 호출했다며 요청 제한 응답을 줄 수 있습니다. 이런 상황을 상위 로직이 매번 처리하게 하면 코드가 지저분해지므로, 재시도 정책을 클라이언트 안에 넣었습니다. 서버 오류와 요청 제한에는 지수 백오프로 간격을 늘려 가며 정해진 횟수까지 다시 시도하고 요청 제한 응답이 다시 시도할 시각을 알려 주면 그 값을 존중해 기다립니다.
반대로 명백한 클라이언트 오류, 예컨대 잘못된 요청이나 인증 실패는 재시도해도 소용이 없으므로 즉시 예외로 올립니다. 재시도할 오류와 그러지 말아야 할 오류를 구분하는 것이 중요합니다. 무엇이든 다시 시도하면 잘못된 요청을 백오프 간격만큼 반복하며 시간만 버리게 됩니다.
인증 키를 로그에 흘리지 않는다
서명 인증 클라이언트를 다루다 보면 디버깅을 위해 요청 내용을 로그로 찍고 싶어집니다. 그런데 여기에는 API 키와 서명이 그대로 들어 있어 무심코 남긴 로그가 곧 자격 증명 유출이 됩니다. 그래서 로그를 내보내기 직전에 키나 시크릿, 토큰처럼 보이는 문자열과 일정 길이 이상의 16진수 덩어리를 자동으로 가리는 필터를 로깅 경로에 붙였습니다.
이렇게 서명 생성, 재시도, 요청 제한 대응, 민감정보 마스킹을 클라이언트 한 겹에 모아 두면, 이 API를 쓰는 상위 파이프라인은 인증의 복잡함을 전혀 몰라도 됩니다. 이 클라이언트가 실제로 어떤 수집 흐름에 쓰였는지는 비동기 리포트 API 수집 패턴에서, 전체 시스템은 멀티채널 광고·정산 데이터 수집 파이프라인 사례에서 볼 수 있습니다.
자주 묻는 질문
서명 인증과 토큰 인증은 무엇이 다른가요?
토큰 인증은 한 번 발급받은 값을 유효 기간 동안 헤더에 그대로 넣는 방식입니다. 서명 인증은 요청마다 그 요청의 시각·메서드·경로로 서명을 새로 계산해 붙입니다. 서명은 짧게만 유효하고 다른 요청에 재사용할 수 없어 더 안전하지만 구현할 때 서명 규칙을 정확히 지켜야 하는 부담이 있습니다.
서명이 자꾸 틀리는데 어디를 봐야 하나요?
대개 메시지를 잇는 순서나 구분자, 시각의 단위에서 어긋납니다. 규격이 시각을 밀리초로 요구하는데 초로 넣거나, 경로에 쿼리 문자열 포함 여부가 다르면 서명이 통째로 달라집니다. 서명 생성을 순수 함수로 떼어 규격의 예시 입력으로 결과를 대조해 보면 원인을 빨리 좁힐 수 있습니다.
재시도는 모든 오류에 하면 되나요?
아니요. 서버 오류와 요청 제한처럼 시간이 지나면 풀리는 오류만 재시도해야 합니다. 잘못된 요청이나 인증 실패 같은 클라이언트 오류는 다시 보내도 같은 결과가 나오므로 즉시 실패로 처리하는 편이 낫습니다. 그래야 잘못된 요청을 반복하며 시간을 낭비하지 않습니다.