인증

팝빌 API를 사용하기 위한 공통 정의 사항과 인증 토큰 발급 및 사용 방법을 안내합니다.

공통 정의 사항

팝빌 API 규격은 다음과 같이 정의합니다.

• RESTful API
• HTTPS 통신 / TLS 1.2, 1.1 지원
• JSON 메시지 포맷

팝빌 API에서 사용하는 Base URL은 다음과 같습니다.

※ ServiceID는 팝빌 API 테스트/운영을 구별하는 고유식별정보입니다.

위 도메인의 IP는 가변적으로 변경됩니다.
방화벽으로 인해 고정 IP가 필요한 경우에는 아래의 Outbound 정보를 등록해야 합니다. 고정 IP를 설정한 뒤에는 아래의 안내된 도메인으로 호출해야 합니다.

인증 방식

팝빌 인증 방식은 팝빌 인증 서버로부터 토큰을 발급받고, 이후 모든 API 호출 시 토큰을 함께 전송하는 방식입니다.

팝빌 인증 토큰을 발급받기 위해서는 먼저 파트너를 식별하기 위한 LinkID와 API 통신전문 변조를 방지하기 위한 SecretKey가 필요합니다.

LinkID와 SecretKey를 이용해 HMAC-SHA256 기반의 Signature를 생성하여 Authorization Header에 기재하는 방식을 사용합니다.

HTTP Authorization Header에 기재되는 정보는 다음과 같습니다.

Authorization: LINKHUB LinkID Signature

Signature에는 전문의 변조방지 부분에 대해서 파트너의 SecretKey로 HMAC-SHA256 알고리즘으로 생성하며, Authorization Header 구성방법에 대한 의사코드(pseudocode)는 다음과 같습니다.

Authorization = "LINKHUB" + " " + LinkID + " " + Signature;

Signature = Base64( HMAC-SHA256( SecretKey, UTF-8-Encoding-Of( StringToSign ) ) );

StringToSign = HTTP-Verb + "\n" +
	Content-MD5 + "\n" +
	Date + "\n" +
	CanonicalizedLINKHUBHeaders + ResourceURI [include query string];

CanonicalizedLINKHUBHeaders = >described below<

Content-MD5는 전문에 Contents가 없는 경우(GET request)에는 빈 문자("")로 처리합니다. Date는 UTC 시간으로 기재되어야 하며, Authorization Header 또는 x-lh-date Header 중 하나의 Header에 반드시 입력되어야 합니다.
Canonicalized-LINKHUBHeaders는 HTTP Header에 팝빌이 정의하는 Header를 추가로 입력하는 정보로 'x-lh-'로 시작하는 HTTP Header에 Canonicalization한 결과입니다.

인증 토큰 발급

• 팝빌 API를 사용하기 위한 인증 토큰을 발급합니다.

Request

#!/bin/bash

LinkID="TESTER" # 팝빌에서 발급받은 API Key의 LinkID
SecretKey="SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=" # 팝빌에서 발급받은 API Key의 SecretKey
AccessID="1234567890" # 팝빌회원 사업자번호
ServiceID="POPBILL_TEST" # 테스트 환경: POPBILL_TEST, 운영 환경: POPBILL
APIVersion="2.0" # API 버전
ForwardedIP="*" # 토큰 사용 허용 IP

RequestBody=$(printf '{"access_id":"%s","scope":["member","110"]}' "$AccessID")

Body=$(echo -n "$RequestBody" | openssl dgst -sha256 -binary | openssl base64)

RequestDT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

StringToSign=$(printf 'POST\n%s\n%s\n%s\n%s\n/%s/Token' "$Body" "$RequestDT" "$ForwardedIP" "$APIVersion" "$ServiceID")

Signature=$(echo -n "$StringToSign" | openssl dgst -sha256 -binary -mac HMAC -macopt key:$(echo -n "$SecretKey" | base64 --decode) | openssl base64)

Authorization="LINKHUB ${LinkID} ${Signature}"

curl --request POST \
  --url 'https://auth.linkhub.co.kr/${ServiceID}/Token' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ${Authorization}' \
  --header 'X-LH-Version: ${APIVersion}' \
  --header 'X-LH-Date: ${RequestDT}' \
  --header 'X-LH-Forwarded: ${ForwardedIP}' \
  --data '$RequestBody'

Response

{
    "session_token": "dGfY0osTAoWNdlNwmugjEDTu...4MuWhVplgLrlQ7FzenX98qiZYDSqQ0ISEOJP",
    "serviceID": "POPBILL_TEST",
    "linkID": "TESTER",
    "userID": "1234567890",
    "partnerCode": "014040000003",
    "usercode": "025070002467",
    "scope": [ "member", "110" ],
    "ipaddress": "*",
    "expiration": "2025-11-19T03:41:17.839Z"
}

인증 토큰 사용

인증 토큰은 팝빌 API를 호출할 때 권한을 검증하는 데 사용됩니다.
토큰은 발급 시점부터 30분간 유효하며, 유효 기간이 지난 후에는 새 토큰을 재발급받아 사용해야 합니다.

팝빌 API를 호출할 때 Bearer 방식으로 Authorization 헤더에 토큰 값을 입력합니다.

Authorization: Bearer {session_token}