Authentication

META API와의 통신에서의 인증 안내

META API와의 통신과정에서 요청의 신뢰성과 무결성 보장을 위해

인증 과정이 필수적으로 요구됩니다.

인증 방식은 두 가지로 구성되어 있으며, 요청 방향에 따라 적용되는 인증 방식이 다릅니다.

에이전트는 상황에 따라 아래 서술된 방법으로 인증을 수행해야 합니다.

---

1. API Key 기반 인증 *required ^{_{에이전트가 META API를 호출할 때}}

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

에이전트는 META API를 호출할 때, 아래 두 값을 반드시 요청 헤더에 포함해야 합니다.

헤더 키

설명

---

agent-id

발급받은 에이전트 식별자

api-key

발급된 API 키

두 값은 META 백오피스의 마이페이지에서 확인 가능합니다.

---

2. 시그니처 기반 인증 *not required ^{_{META가 에이전트 시스템 API를 호출할 때}}

META가 에이전트 서버로 요청을 보낼 때는, 요청이 위·변조되지 않았음을 검증할 수 있도록

**시그니처 기반 인증(HMAC-SHA256)**을 사용합니다.

META는 아래 두 값을 요청 헤더에 포함하여 전송합니다.

헤더 키

설명

---

x-signature

서명 문자열 (HMAC-SHA256)

x-timestamp

요청 시각 (UNIX timestamp in milliseconds)

---

에이전트는 META로 부터 수신한 요청이 신뢰 가능한지 검증해야 하며,

검증은 아래의 META에서 제공한 검증 함수로 수행할 수 있습니다.

HMAC 서명 secret key:

암호화에 사용되는 secret key는 에이전트에 발급된 api key 입니다.

서명 원본 문자열 형식:

{METHOD}|{TIMESTAMP}|{BODY or QUERY_STRING}

예시:

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

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

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

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

pseudocode

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 }

Java

PHP

Javascript

C#

Python