// sdk / overview

API 연동 SDK

파트너가 end-user의 자격증명 등록을 managed SDK에 위임하는 흐름입니다. 인증 정보는 end-user 브라우저에서 입력·암호화되며 파트너 서버를 거치지 않습니다.

전체 흐름

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

1. 백엔드에서 세션 발급

백엔드가 API 키로 호출합니다. 발급된 세션의 사업자번호는 API 키에 연결된 워크스페이스에서 정해집니다.

# 파트너 백엔드 (언어 무관). API 키는 브라우저에 노출하지 않습니다.
POST /api/v1/registration-sessions
Authorization: Bearer h6s_live_...
Content-Type: application/json

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

응답의 sessionToken 을 프론트엔드 SDK에 넘깁니다.

{
  "sessionId": "0193...",
  "sessionToken": "reg_AbCdEf...",   // SDK 에 넘기는 1회용 토큰
  "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. 등록 완료 통보

end-user가 등록을 마치면 SDK 콜백(onSuccess)으로 sessionId 가 전달됩니다. 서버 상태 동기화가 필요하면 GET /api/v1/registration-sessions/{id} 폴링으로 결과를 확인할 수 있습니다.

핵심 보장

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