headless

// api guide / credentials

자격증명 등록 (콘솔)

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

등록 흐름

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

왜 콘솔에서만?

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

다음 단계