// sdk / overview

플랫폼 통합 SDK

파트너가 자기 end-user 의 자격증명을 headless에 등록시키는 위임 흐름입니다. 인증 정보는 headless 호스팅 페이지에서만 처리되며 파트너 서버를 거치지 않습니다.

전체 흐름

백엔드가 1회용 세션 토큰을 발급하고, 프론트엔드 SDK 가 그 토큰으로 등록 UI 를 엽니다. 아래 세 단계로 끝납니다.

1. 백엔드 — 세션 발급

파트너 백엔드가 API 키로 호출합니다. partner 키는 end-user 의 사업자번호를 X-H6S-Business 헤더로 함께 보냅니다 (workspace 키는 발급 없이도 사업자번호가 정해집니다).

# 파트너 백엔드 (언어 무관). API 키는 브라우저에 노출하지 않습니다.
POST /api/v1/registration-sessions
Authorization: Bearer h6s_live_...
X-H6S-Business: 1234567890        # end-user 의 사업자번호 10자리
Content-Type: application/json

{
  "registrationOptions": [
    { "kind": "CERTIFICATE" },
    { "kind": "PROVIDER_LOGIN", "providerCode": "HOMETAX" }
  ],
  "originAllowlist": ["https://partner.example.com"],
  "clientReferenceId": "user-42"
}

응답의 sessionToken 을 프론트엔드 SDK 에 넘기고, hostedUrl 은 end-user 에게 직접 링크로 전달할 때 사용합니다.

{
  "sessionId": "0193...",
  "sessionToken": "reg_AbCdEf...",   // SDK 에 넘기는 1회용 토큰
  "hostedUrl": "<hosted-registration-url>",
  "expiresAt": "2026-05-22T08:30:00Z",
  "status": "PENDING"
}

2. 프론트엔드 — 등록 UI 열기

토큰을 받아 SDK 로 등록 UI 를 엽니다. 두 방식 중 스택에 맞는 가이드를 따르세요.

script tag · npm

Vanilla JS

jQuery·Vue·서버 렌더링 등 어떤 스택에서도 동작합니다.

가이드 보기

npm

React

declarative 컴포넌트와 hook. peer dep react ≥ 18.

가이드 보기

3. 등록 완료 통보

iframe 모드에서 end-user 가 등록을 마치면 SDK 콜백(onSuccess)으로 credentialId 가 전달됩니다. hosted page 링크나 모바일 fallback 으로 열린 페이지에서는 SDK 콜백이 실행되지 않으므로, GET /api/v1/registration-sessions/{id} 폴링으로 결과를 확인합니다.

핵심 보장

인증 정보는 파트너 도메인에 도달하지 않습니다
토큰은 1회용입니다 — 등록 성공 또는 만료/취소 시 영구 무효
세션 발급 시 지정한 사업자번호·인증 방식·기관 외 입력은 거부됩니다
등록 완료는 SDK 콜백 또는 세션 상태 조회로 확인합니다