// api guide / credentials

자격증명 등록 (콘솔)

은행/홈택스 자격증명은 민감 값이라 콘솔 UI 안내를 따라 한 번 등록해 주세요. 등록 후 credentialHealth 상태를 확인해 입력 오류를 빠르게 찾을 수 있습니다. 외부 API로 자격증명을 자동 등록하는 흐름은 지원하지 않습니다. 등록 후에는 API 키로 수집 요청을 실행해 주세요.

플랫폼 사업자가 자기 end-user 의 인증서를 등록받아야 한다면 SDK / 위임 등록 흐름 에서 확인할 수 있습니다. end-user가 headless 호스팅 페이지에서 직접 입력하므로 파트너 서버는 거치지 않습니다.

등록 흐름

  1. 콘솔 → 자격증명 에서 기관을 골라 주세요. 지원 기관은 데이터 카탈로그 → 지원 금융기관 에서 확인할 수 있습니다.
  2. 인증 방식을 선택해 주세요. 공동인증서 (GLOBAL)면 PFX 파일 하나를 모든 은행·홈택스에 함께 사용하고, provider ID·비밀번호면 그 기관에만 매칭됩니다. 두 방식은 함께 등록할 수 있습니다.
  3. 값을 저장하면 credentialHealth 상태가 표시됩니다. 입력값이 올바르면 VERIFIED, 오류가 있으면 NEEDS_REVERIFICATION 으로 표시되니 값을 다시 입력해 주세요.
  4. 콘솔 → API 키 에서 라이브 키를 발급해 시스템의 secret 매니저에 저장해 주세요. API 키 1개로 등록된 자격증명이 자동 매칭됩니다.

왜 콘솔에서만?

  • 자격증명은 민감 값이라 등록 단계에서 사람 확인이 필요합니다. 외부 API로 자동화하면 사고 추적이 어려워지고 운영 복잡도가 높아집니다.
  • 공동인증서(PFX)는 파일 업로드, 비밀번호, 개인키를 함께 입력해야 해서 안내가 있는 폼 기반 등록이 가장 안전합니다.
  • 자격증명 상태(마지막 검증 시각·실패 사유·재인증 필요 여부)도 콘솔에서 확인합니다.

다음 단계