# Authentication

EBP API를 사용하기 위해 모든 요청에는 인증 정보와 무결성 검증을 위한 헤더가 포함되어야 합니다.

## 1. Access Key

EBP API를 호출하기 위해서는 다음 헤더를 반드시 포함해야 합니다.

| 헤더명 | 설명 | 비고 |
| :--- | :--- | :--- |
| `X-Access-Key` | EBP에서 발급한 스토어 및 채널별 인증 키 | 모든 요청 필수 |

`X-Access-Key`는 EBP 시스템 접근 권한을 확인하는 데 사용됩니다. 스토어 및 채널별로 고유하게 발급되며, 보안을 위해 노출되지 않도록 관리해 주시기 바랍니다.

> [!CAUTION] **유효기간 및 갱신**
> `X-Access-Key`의 유효기간은 최초 발급 후 **1년**입니다. 유효기간이 종료되기 전에 반드시 갱신 절차를 진행해야 하며, 만료된 키로는 API 호출이 불가합니다.

## 2. Signature

모든 API 요청의 무결성을 보장하기 위해 `X-EBP-Signature` 헤더를 포함해야 합니다. 이 값은 SHA-256 알고리즘을 사용하여 생성합니다.

### 생성 규칙 (Input Rules)

1.  Input Message 구성:
    - GET: 전체 Query String (첫 문자 `?` 포함). 예) `?countryCode=UK&storeId=123`
    - POST: 원본 Request Body (공백, 줄바꿈, 키 순서 등 전송되는 데이터 그대로 유지). 예) `{"userNo":123,"items":["p1"]}`
2.  문자열 결합 (Concatenation): `Input Message + Hash Key`
    - Hash Key는 EBP에서 발급하며, 스토어별로 관리됩니다.
3.  해싱 (Hashing): 결합된 문자열을 SHA-256 알고리즘으로 해싱합니다. (문자 인코딩은 UTF-8 권장)
4.  인코딩 (Encoding): 해싱 결과(32바이트)를 Hex 문자열(Hex-encoded string)로 변환하여 헤더 값으로 설정합니다.

### 생성 예제 (Example Code)

[tabs]
[tab:Java]
```java
import org.apache.commons.codec.digest.DigestUtils;

/**
 * Apache Commons Codec 라이브러리를 활용한 시그니처 생성
 * @param message  GET: Query String(starts with '?') / POST: JSON Body
 * @param hashKey  EBP에서 발급한 Hash Key
 */
public String generateSignature(String message, String hashKey) {
    return DigestUtils.sha256Hex(message + hashKey);
}
```
[tab:Node.js]
```javascript
const crypto = require('crypto');

/**
 * Node.js 기본 crypto 모듈을 활용한 시그니처 생성
 */
function generateSignature(message, hashKey) {
  return crypto
    .createHash('sha256')
    .update(message + hashKey)
    .digest('hex');
}
```
[tab:JavaScript(Browser)]
```javascript
/**
 * Browser Web Crypto API를 활용한 비동기 시그니처 생성
 */
async function generateSignature(message, hashKey) {
  const encoder = new TextEncoder();
  const data = encoder.encode(message + hashKey);
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
  
  // ArrayBuffer를 Hex 문자열로 변환
  return Array.from(new Uint8Array(hashBuffer))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');
}
```
> [!WARNING] **보안 주의사항 (Security Notice)**
> 브라우저(Client-side) 자바스크립트에서 시그니처를 생성할 경우 소스 코드 내에 **Hash Key가 외부에 노출**될 위험이 매우 높습니다. 테스트 목적 외의 **실제 운영 환경에서는 반드시 서버 사이드(Java, Node.js 등)에서 시그니처를 생성**하여 전달하시기 바랍니다.

[tab:Postman(Pre-request)]
```javascript
// 1. 설정: EBP에서 발급받은 Hash Key (환경 변수 또는 컬렉션 변수 권장)
const hashKey = pm.variables.get('hashKey') || 'YOUR_HASH_KEY';
let message = "";

// 2. HTTP Method에 따른 메시지 구성
if (pm.request.method === 'GET') {
    // URL에서 '?'를 포함한 전체 Query String 추출
    const urlString = pm.request.url.toString();
    const qIndex = urlString.indexOf('?');
    message = qIndex !== -1 ? urlString.substring(qIndex) : "";
} else {
    // Body 내의 변수({{...}})를 실제 값으로 치환한 원본 데이터 사용
    message = pm.variables.replaceIn(pm.request.body.raw || "");
}

// 3. SHA-256 해시 생성 및 헤더 설정
const signature = CryptoJS.SHA256(message + hashKey).toString();

pm.request.headers.upsert({
    key: 'X-EBP-Signature',
    value: signature
});
```
[/tabs]

---

**문의:** [ebp-server@lge.com](mailto:ebp-server@lge.com)