Authentication

This document describes below the common definitions required to use the POPBiLL API, and the Auth token issuance and usage method.

Common definitions

The POPBiLL API specification is defined as follows.

• RESTful API
• HTTPS communication / Supports TLS 1.2 and 1.1
• JSON message format

The Base URL used by the POPBiLL API is as follows.

※ ServiceID is an Identification number that distinguishes POPBiLL API Test/Production.

The IP of the above domains changes dynamically.
If a static IP is required due to a firewall, you must register the Outbound information listed below. After setting a static IP, you must call using the domains listed below.

Authentication Method

The POPBiLL authentication method issues a token from the POPBiLL authentication server, and then sends the token together with every API call.

To issue a POPBiLL Auth token, you first need a LinkID to identify the partner and a SecretKey to prevent tampering of API messages.

A Signature based on HMAC-SHA256 is generated using LinkID and SecretKey, and written in the Authorization Header.

The information written in the HTTP Authorization Header is as follows.

Authorization: LINKHUB LinkID Signature

Signature is generated using the partner’s SecretKey with the HMAC-SHA256 algorithm for the anti-tampering portion of the message. The pseudocode for constructing the Authorization Header is as follows.

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<

If there is no content in the message (GET request), Content-MD5 is treated as an empty string (””).
Date must be written in UTC time, and must be entered in either the Authorization Header or the x-lh-date Header.
Canonicalized-LINKHUBHeaders is additional header information defined by POPBiLL. It is the canonicalized result of HTTP headers that start with x-lh-.

Auth token issuance

• Issues an Auth token to use the POPBiLL API.

Request

#!/bin/bash

LinkID="TESTER" # LinkID of the API Key issued by POPBiLL
SecretKey="SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=" # SecretKey of the API Key issued by POPBiLL
AccessID="1234567890" # POPBiLL member Business Registration Number
ServiceID="POPBILL_TEST" # Test environment: POPBILL_TEST, Production environment: POPBILL
APIVersion="2.0" # API version
ForwardedIP="*" # Allowed IP for token usage

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"
}

Auth token usage

An Auth token is used to verify authorization when calling the POPBiLL API.
The token is valid for 30 minutes from issuance, and after it expires you must reissue a new token.

When calling the POPBiLL API, enter the token value in the Authorization header using the Bearer scheme.

Authorization: Bearer {session_token}