1. Overview

Tomo IDV 서비스는 User의 신분증 인증을 수행하기 위한 절차(IDV Service)를 제공합니다. IDV Service는 IDV Server, IDV App으로 구성돼있으며, Client는 IDV Server를 통해 인증을 수행 한 후, User를 IDV App으로 연결시켜 신분증 인증을 수행할 수 있습니다.

Requirement

• TLS 1.3 (TLS 1.1, TLS 1.2는 지원하지 않습니다)

2. Sequence diagram

• TomoIDV API를 사용하기 위해 가장 먼저 TomoIDV console을 통하여 Client ID, Secret key를 발급 받습니다. 발급 과정은 Register client 문서를 참고해주시기 바랍니다. 이 정보를 이용하여 Client Server를 인증하면, API Server로부터 TomoIDV 자원에 접근할 수 있는 Access token을 발급(과정 [1])받을 수 있습니다.
• 발급받은 Access Token을 이용하여 Client Assertion을 만든 후, 헤더에 추가하여 신분증 인증을 위한 start작업(과정 [2])을 수행합니다. 다른 모든 API에서 이러한 Authentication 헤더를 요구합니다.
• start의 결과로 idv_start_uri를 응답합니다. User는 이 uri를 통해 IDV App에 접속하여 인증 화면을 볼 수 있고, 이 화면에서 신분증 인증을 수행(과정 [3])합니다.
• User가 인증을 마치면, IDV App 에서 자동적으로 callback_url을 통해 Client App으로 복귀(과정 [4]) 합니다.

sequenceDiagram
participant ClientApp as Client App
participant ClientServer as Client Server
participant IDVServer as IDV Server
participant IDVApp as IDV App

ClientServer->>+IDVServer: [1] Get Access Token (POST /v1/oauth2/token)
IDVServer-->>-ClientServer: 200 OK

ClientApp->>+ClientServer: Start IDV 
ClientServer->>+IDVServer: [2] Start IDV(Get IDV URL) (POST /v1/idv/<country_code>/start)
IDVServer-->>-ClientServer: 200 OK
ClientServer-->>-ClientApp: 200 OK

ClientApp->>IDVApp: [3] Launch IDV App

IDVApp-->>ClientApp: [4] Return to Origin App

ClientServer->>+IDVServer: [5] Get Kyc (POST /v1/idv/<country_code>/kyc/get)
IDVServer->>-ClientServer: 200 OK

3. Specification

[1] Get Access Token

POST /v1/oauth2/token

TomoIDV API에 접근할 수 있는 Access Token을 발급 받기 위해, console로부터 발급 받은 Secret key를 이용하여 client_assertion을 만들고, 정해진 Body 양식을 제출해야합니다. tomo-idv-client-node SDK를 이용하면, 요청에 필요한 Headers와 Body를 쉽게 얻을 수 있습니다. SDK 사용 방법은 Client SDK 문서를 참고해주십시오. 직접 client_assertion을 생성하여 사용 할 시 Creating Client Assertion 문서를 참고해주십시오.

Request

Client SDK

Client SDK를 이용하면 손쉽게 Access token 양식을 작성할 수 있습니다.

import { createClientAssertion, buildTokenRequest } from 'tomo-idv-client-node';

// Create client assertion JWT
const clientAssertion = createClientAssertion({
  client_id: 'your-client-id',
  secret_key: 'your-secret-key',
  base_url: 'base-url'
});

// Build token request
const { headers, body } = buildTokenRequest(clientAssertion);

// Use the token request
const response = await fetch('<https://test.tomopayment.com/v1/oauth2/token>', {
  method: 'POST',
  headers: headers,
  body: body
});