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 안내가 결정적이라 폼 기반이 가장 안전하다.
  • 자격증명 상태 (마지막 검증 시각·실패 사유·재인증 필요 여부) 도 콘솔에서 확인한다.

다음 단계