인증 API 개요
개요
DTA-Wide API는 다음과 같은 두 가지 주요 인증 메커니즘을 제공합니다:
- 앱 인증 (App Authentication): 모바일 앱과 백엔드 간의 안전한 통신을 위한 인증입니다.
- 사용자 인증 (User Authentication): 사용자 계정의 신원을 확인하고 접근 권한을 부여하는 인증입니다.
인증 API 목록
인증 관련 API는 다음과 같습니다:
앱 인증 API
앱 인증은 사용자 인증 전에 가장 먼저 수행되어야 하는, 애플리케이션 레벨의 인증입니다.
| API 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/de/v1/auth/app/challenge | POST | 챌린지 요청 |
/de/v1/auth/app/verify | POST | 챌린지 확인 및 앱 토큰 발급 |
앱 무결성 검증 API (v2)
앱 무결성 검증은 정품 앱·정품 기기 여부를 플랫폼 네이티브 메커니즘(iOS App Attest / Android Play Integrity)으로 확인합니다. Firebase App Check 대체(BSI O.Resi_5)이며, app-token 발급과 분리된 검증 전용 API입니다.
| API 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v2/security/ios/attest/challenge | POST | iOS challenge 발급 |
/v2/security/ios/attest/key | POST | iOS 키 등록 (첫 실행 1회) |
/v2/security/ios/attest/assert | POST | iOS 무결성 증명 (매번) |
/v2/security/android/integrity/challenge | POST | Android nonce 발급 |
/v2/security/android/integrity/verify | POST | Android 무결성 토큰 검증 (매번) |
약관 관리 API
서비스 약관 목록을 조회합니다.
| API 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/de/v1/auth/agreements | GET | 약관 목록 조회 |
사용자 인증 API
사용자 로그인, 회원 가입 등 기본적인 인증 관련 API입니다.
EU v2 인증 API (eID + Native 2FA)
독일(EU) 환자용 v2 인증 API. gematik eID 또는 디바이스 키 기반 Native 2FA 둘 중 하나를 사용합니다. 흐름(가입 → 로그인 세션 반환 → 서비스 활성화 → 재로그인) 구조이며, Authorization: Bearer 단일 채널 정책을 따릅니다. 모든 인증 응답(register·login)은 LoginV2ResponseDto(v1 LoginResponseDto와 동일 형태) 로 통일돼 있습니다.
| API 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v2/auth/register/eid/initialize·/complete | POST | EU eID 가입 (complete 가 LoginV2ResponseDto 반환) |
/v2/auth/register/native | POST | EU Native 2FA 가입 (공개키만·단일 endpoint·LoginV2ResponseDto 반환, Plan 209) |
/v2/auth/login/eid/initialize·/complete | POST | EU eID 로그인 (first-login / 재로그인 / 새 기기 — 서버 분기) |
/v2/auth/login/eid/link/*·/unlink | POST·GET | EU eID 링크/언링크 (method 전환) |
/v2/auth/login/native/initialize·/complete | POST | EU Native 2FA 로그인 (재로그인=서명 / keyless=공개키 upsert) |
/v2/auth/login/native/link | POST | EU Native 2FA method 전환 (OTP step-up + 새 공개키, Plan 209) |
/v2/auth/user-cycle/activate·/state | POST·GET | 서비스 활성화 + 상태 조회 (uci 토큰 재발급) |
- EU eID 회원가입 API 상세
- EU Native 2FA 회원가입 API 상세
- EU eID 로그인 API 상세
- EU Native 2FA 로그인 API 상세
- Auth 도메인 endpoints
인증 흐름
일반적인 인증 흐름은 다음과 같습니다:
- 앱 인증을 통해
appToken획득 appToken을 사용하여 사용자 로그인 요청- 로그인 성공 시
accessToken과refreshToken획득 - 보호된 리소스 접근 시
accessToken사용 accessToken만료 시refreshToken으로 갱신
중요
인증 관련 상세 개념 및 보안 원칙은 인증 가이드라인을 참조하세요.