Authentication

API 인증

HighEnd 통합 API와의 통신은 요청의 신뢰성과 무결성 보장을 위해 인증 과정이 필수적으로 요구됩니다.

인증 방식은 요청 방향에 따라 구분되며, 파트너사는 상황에 맞춰 적절한 방식으로 인증을 수행해야 합니다.

1. API Key 기반 인증

필수 : 파트너사 서버가 HighEnd 플랫폼 서버로 API 요청시 사용되는 인증 방식입니다.

파트너사가 HighEnd API를 호출할 때는 API Key 기반 인증을 사용하여 요청 주체를 식별합니다.

모든 요청 헤더에 아래 두 값을 반드시 포함해야 합니다.

HighEnd 백오피스의 마이페이지에서 AGENT ID 와 API KEY 를 확인 하실 수 있습니다.

헤더 키

설명

agent-id

발급받은 파트너사 식별자

api-key

발급된 API 키

2. 시그니처 기반 인증

선택 사항 : HighEnd 플랫폼에서 파트너사 서버로 웹훅 발송시 사용되는 인증 방식입니다.

HighEnd가 파트너사 서버로 요청을 보낼 때는 요청의 위변조 방지를 위해 시그니처 기반 인증(HMAC-SHA256) 을 사용합니다.

HighEnd는 아래 두 값을 요청 헤더에 포함하여 전송합니다. 파트너사는 수신한 요청이 신뢰 가능한지 검증해야 합니다.

검증은 아래의 샘플 검증 함수를 참고하여 수행할 수 있습니다.

헤더 키

설명

x-signature

서명 문자열 (HMAC-SHA256)

x-timestamp

요청 시각 (UNIX timestamp in milliseconds)

HMAC 서명 secret key :

암호화에 사용되는 secret key는 파트너사에 발급된 api-key 입니다

서명 원본 문자열 형식 : {METHOD}|{TIMESTAMP}|{BODY or QUERY_STRING}

예시 : POST|1721361012345|{"user_id":"abc","amount":1000}

x-timestamp는 유닉스 시간(ms) 기준으로 전송되며,

현재 시각과의 차이가 ±10초 이상일 경우 유효하지 않은 요청으로 판단됩니다.

이는 네트워크 지연 및 리플레이 공격 방지를 위한 안전 장치입니다.

function verify_signature(request, api_key):
    # 1. 헤더에서 시그니처와 타임스탬프 가져오기
    signature = request.headers["x-signature"]
    timestamp_str = request.headers["x-timestamp"]

    if not signature or not timestamp_str:
        return { success: false, cause: "missing headers" }

    # 2. 타임스탬프 숫자 변환 및 만료 체크 (10초 초과 시 실패)
    timestamp = Number(timestamp_str)
    now = 현재시각_밀리초()
    if isNaN(timestamp) or abs(now - timestamp) > 10000:
        return { success: false, cause: "timestamp expired" }

    # 3. HTTP 메서드와 페이로드 만들기
    method = request.method.upper()
    if method == "GET":
        payload = JSON.stringify(request.query or {})
    else:
        payload = JSON.stringify(request.body or {})

    # 4. 원본 문자열 구성
    raw = method + "|" + timestamp + "|" + payload

    # 5. HMAC-SHA256 서명 계산 (hex 소문자)
    expected = HMAC_SHA256(raw, api_key).hex_lowercase()

    # 6. 서명 비교
    if expected != signature:
        return { success: false, cause: "verify failed" }

    return { success: true }

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Map;

public static VerifyResult verifySignature(
    String method,
    String bodyJson,
    Map<String, String> headers,
    String apiKey,
    Map<String, String> queryParams
) {
    String sig = headers.get("x-signature");
    String tsStr = headers.get("x-timestamp");

    if (sig == null || tsStr == null) return VerifyResult.fail("missing or invalid headers");

    long timestamp;
    try { timestamp = Long.parseLong(tsStr); }
    catch (NumberFormatException e) { return VerifyResult.fail("invalid timestamp"); }

    if (Math.abs(System.currentTimeMillis() - timestamp) > 10000)
        return VerifyResult.fail("timestamp expired");

    String payload;
    if ("GET".equalsIgnoreCase(method)) {
        StringBuilder json = new StringBuilder("{");
        if (queryParams != null && !queryParams.isEmpty()) {
            boolean first = true;
            for (Map.Entry<String, String> entry : queryParams.entrySet()) {
                if (!first) json.append(",");
                json.append("\"").append(entry.getKey()).append("\":\"").append(entry.getValue()).append("\"");
                first = false;
            }
        }
        json.append("}");
        payload = json.toString();
    } else {
        payload = (bodyJson != null && !bodyJson.isEmpty()) ? bodyJson : "{}";
    }

    String raw = method.toUpperCase() + "|" + timestamp + "|" + payload;
    try {
        Mac hmac = Mac.getInstance("HmacSHA256");
        hmac.init(new SecretKeySpec(apiKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] hash = hmac.doFinal(raw.getBytes(StandardCharsets.UTF_8));
        StringBuilder hex = new StringBuilder();
        for (byte b : hash) hex.append(String.format("%02x", b));

        return hex.toString().equals(sig)
            ? VerifyResult.ok()
            : VerifyResult.fail("verify failed");
    } catch (Exception e) {
        return VerifyResult.fail("crypto error");
    }
}

function verifySignature($method, $bodyJson, $headers, $apiKey, $queryParams = null) {
    $signature = $headers['x-signature'] ?? null;
    $timestamp = $headers['x-timestamp'] ?? null;

    if (!$signature || !$timestamp || !is_numeric($timestamp)) {
        return [ "success" => false, "cause" => "missing or invalid headers" ];
    }
    if (abs((int)(microtime(true) * 1000) - (int)$timestamp) > 10000) {
        return [ "success" => false, "cause" => "timestamp expired" ];
    }

    $methodUpper = strtoupper($method);
    if ($methodUpper === 'GET') {
        $payload = json_encode($queryParams ?? [], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
    } else {
        $payload = $bodyJson ?: '{}';
    }

    $raw = $methodUpper . "|" . $timestamp . "|" . $payload;
    $expected = hash_hmac('sha256', $raw, $apiKey);

    return $signature === $expected
        ? [ "success" => true ]
        : [ "success" => false, "cause" => "verify failed" ];
}

const crypto = require('crypto');

function verifySignature(req, apiKey) {
  const signature = req.headers['x-signature'];
  const tsStr = req.headers['x-timestamp'];
  const timestamp = Number(tsStr);

  if (!signature || !tsStr || isNaN(timestamp)) {
    return { success: false, cause: 'missing or invalid headers' };
  }
  if (Math.abs(Date.now() - timestamp) > 10000) {
    return { success: false, cause: 'timestamp expired' };
  }

  const method = req.method.toUpperCase();
  const payloadObj = method === 'GET' ? (req.query || {}) : (req.body || {});
  const payloadStr = JSON.stringify(payloadObj);

  const raw = `${method}|${timestamp}|${payloadStr}`;
  const expected = crypto.createHmac('sha256', apiKey).update(raw).digest('hex');

  return signature === expected
    ? { success: true }
    : { success: false, cause: 'verify failed' };
}

module.exports = { verifySignature };

using System;
using System.Text;
using System.Text.Json;
using System.Collections.Generic;
using System.Security.Cryptography;

public static VerifyResult VerifySignature(
    string method,
    string bodyJson,
    Dictionary<string, string> headers,
    string apiKey,
    Dictionary<string, string> queryParams
) {
    if (!headers.TryGetValue("x-signature", out var signature) ||
        !headers.TryGetValue("x-timestamp", out var tsStr) ||
        !long.TryParse(tsStr, out var timestamp)) {
        return new VerifyResult { Success = false, Cause = "missing or invalid headers" };
    }

    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeMilliseconds() - timestamp) > 10000) {
        return new VerifyResult { Success = false, Cause = "timestamp expired" };
    }

    var payload = method.Equals("GET", StringComparison.OrdinalIgnoreCase)
        ? JsonSerializer.Serialize(queryParams ?? new Dictionary<string, string>())
        : (string.IsNullOrEmpty(bodyJson) ? "{}" : bodyJson);

    var raw = $"{method.ToUpper()}|{timestamp}|{payload}";
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiKey));
    var expected = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(raw))).ToLower();

    return signature == expected
        ? new VerifyResult { Success = true }
        : new VerifyResult { Success = false, Cause = "verify failed" };
}

import time, hmac, hashlib, json

def verify_signature(method, body_json, headers, api_key, query_params=None):
    sig = headers.get("x-signature")
    ts_str = headers.get("x-timestamp")

    try:
        timestamp = int(ts_str)
    except (ValueError, TypeError):
        return { "success": False, "cause": "missing or invalid headers" }

    if not sig or abs(int(time.time() * 1000) - timestamp) > 10000:
        return { "success": False, "cause": "timestamp expired" }

    if method.upper() == "GET":
        payload = json.dumps(query_params or {}, separators=(",", ":"))
    else:
        payload = body_json or "{}"

    raw = f"{method.upper()}|{timestamp}|{payload}"
    expected = hmac.new(api_key.encode(), raw.encode(), hashlib.sha256).hexdigest()

    return { "success": sig == expected, "cause": None if sig == expected else "verify failed" }

PreviousOverview NextCallback

Last updated 3 months ago

import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.util.Map; public static VerifyResult verifySignature( String method, String bodyJson, Map<String, String> headers, String apiKey, Map<String, String> queryParams ) { String sig = headers.get("x-signature"); String tsStr = headers.get("x-timestamp"); if (sig == null || tsStr == null) return VerifyResult.fail("missing or invalid headers"); long timestamp; try { timestamp = Long.parseLong(tsStr); } catch (NumberFormatException e) { return VerifyResult.fail("invalid timestamp"); } if (Math.abs(System.currentTimeMillis() - timestamp) > 10000) return VerifyResult.fail("timestamp expired"); String payload; if ("GET".equalsIgnoreCase(method)) { StringBuilder json = new StringBuilder("{"); if (queryParams != null && !queryParams.isEmpty()) { boolean first = true; for (Map.Entry<String, String> entry : queryParams.entrySet()) { if (!first) json.append(","); json.append("\"").append(entry.getKey()).append("\":\"").append(entry.getValue()).append("\""); first = false; } } json.append("}"); payload = json.toString(); } else { payload = (bodyJson != null && !bodyJson.isEmpty()) ? bodyJson : "{}"; } String raw = method.toUpperCase() + "|" + timestamp + "|" + payload; try { Mac hmac = Mac.getInstance("HmacSHA256"); hmac.init(new SecretKeySpec(apiKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); byte[] hash = hmac.doFinal(raw.getBytes(StandardCharsets.UTF_8)); StringBuilder hex = new StringBuilder(); for (byte b : hash) hex.append(String.format("%02x", b)); return hex.toString().equals(sig) ? VerifyResult.ok() : VerifyResult.fail("verify failed"); } catch (Exception e) { return VerifyResult.fail("crypto error"); } }

hashtagAPI 인증

hashtag1. API Key 기반 인증

hashtag2. 시그니처 기반 인증

API 인증

1. API Key 기반 인증

2. 시그니처 기반 인증