동의 모델
기본 차단 (deny-by-default)
이 API의 출발점은 "아무것도 제공하지 않는다"입니다. 점수·등급·사유코드는 사용자가 앱에서 특정 기관 × 특정 목적에 대해 명시적으로 동의한 경우에만 반환됩니다.
- 동의는 기관(clientId) + 목적(purpose) 단위로 부여됩니다. 다른 목적으로는 재사용할 수 없습니다.
- 사용자는 언제든 앱에서 동의를 철회할 수 있고, 철회 즉시 조회가 거부됩니다.
- 동의에는 만료 시각이 있으며, 만료 후에는 재동의가 필요합니다.
- 동의 없음·철회·만료·주체 없음은 FI 관점에서 구분 불가하게 거부됩니다(배치는 단일 DENIED 라벨, 타이밍 균일화 포함) — 거부 응답으로 가입 여부를 추론할 수 없습니다.
파트너 전용 익명 ID (pairwise 식별자)
FI가 보는 유일한 주체 식별자는 pairwiseSub입니다.
- 같은 사용자라도 기관마다 다른 값이 발급됩니다 — 기관 간 대조(cross-linking)로 사용자를 결합할 수 없습니다.
- 내부 식별자(civilId/userId)나 실명·연락처는 이 API 표면에 절대 나타나지 않습니다.
pairwiseSub는 파트너 로그인(SSO) 동의 과정에서 발급된 값을 그대로 사용합니다.
데이터 카테고리
동의는 무엇을 공유할지를 카테고리 단위로 제한합니다. 동의 상태 응답의
dataCategories(CSV 문자열)에서 확인할 수 있습니다.
| 카테고리 | 제공 데이터 | 기본 포함 |
|---|---|---|
score | 점수(0~850) | 기본 |
tier | 등급(EXCELLENT~POOR) | 기본 |
reason-codes | 사유코드(응답당 최대 4건) | 기본 |
contributions | 피처별 기여 상세(응답의 contributions 블록) | 선택 — 명시 동의 시에만 |
history | 점수 이력(GET /fi/score/history) | 선택 — 명시 동의 시에만 |
monitoring | 지속 모니터링 웹훅(score.updated·tier.changed) | 선택 — 명시 동의 시에만 |
consent.revoked 웹훅은 카테고리와 무관하게 발송됩니다 —
철회 사실 자체는 파트너가 알아야 데이터 보관을 중단할 수 있기 때문입니다. 철회 후에는 이 이벤트 외에
어떤 이벤트도 발송되지 않습니다.동의 흐름
- FI가
POST /fi/consent/requests로 동의를 요청 → 사용자 앱에 인앱 알림 발송 - 사용자가 앱에서 목적·카테고리를 확인하고 승인(또는 무시/거절)
- 승인 시 동의 영수증(consent receipt)이 생성되고, FI는
GET /fi/consent/{consentReceiptId}로 상태 확인 가능 - 이후
POST /fi/score/query등 조회 가능 — 매 조회가 동의 검사를 통과해야 함 - 사용자가 철회하면 즉시 거부로 전환되고
consent.revoked웹훅 발송
사용자에게 보이는 것
모든 조회는 접근로그에 기록되며, 사용자는 앱에서 "어느 기관이 언제 무슨 목적으로 내 점수를 조회했는지"를 볼 수 있습니다. 접근로그는 해시체인으로 연결되어 사후 변조를 탐지할 수 있습니다 (컴플라이언스 참고).