---
title: "인증"
description: "모든 요청은 x-api-key 헤더의 API 키로 인증합니다."
---

`gateway.apinoa.com`으로 보내는 모든 요청에는 `x-api-key` 헤더에 API 키가 있어야 합니다. 다른 인증
방식은 없으며, 키가 없는 요청은 처리되지 않습니다.

## 키 발급

**대시보드 > API 키**에서 키를 만드세요. 전체 키는 **만드는 순간 한 번만** 보여줍니다 — 그때 복사해
안전한 곳에 보관하세요. 잃어버렸다면 새 키를 만들고 이전 키를 폐기하면 됩니다.

키는 여러 개를 동시에 둘 수 있습니다. 중단 없이 키를 교체하는 방법이 이것입니다: 새 키를 만들고,
트래픽을 옮긴 뒤, 이전 키를 폐기합니다.

## 모든 요청에 포함하기

```bash
curl -X POST https://gateway.apinoa.com/v1/aliexpress/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "query": "phone case" }'
```

```javascript
const response = await fetch("https://gateway.apinoa.com/v1/aliexpress/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.APINOA_API_KEY,
  },
  body: JSON.stringify({ query: "phone case" }),
});
```

## 키는 서버에만 두세요

키는 잔액을 씁니다. API는 백엔드에서 호출하고, 키는 시크릿 저장소나 환경 변수에 보관하세요.
브라우저, 모바일 앱, 공개 저장소에 두면 누구나 읽어서 여러분의 잔액으로 호출할 수 있습니다.

키가 노출됐을 수 있다면 **대시보드 > API 키**에서 폐기하세요. 폐기된 키는 즉시 작동을 멈춥니다.

## 인증이 실패할 때

| 상태 | 코드 | 의미 |
|------|------|------|
| 401 | `UNAUTHORIZED` | `x-api-key` 헤더가 없거나, 키가 유효하지 않거나 폐기됨 |
| 402 | `INSUFFICIENT_BALANCE` | 키는 유효하지만 잔액이 이 호출을 감당하지 못함 |

각 호출은 [요금 페이지](/pricing)의 단가로 잔액에서 차감됩니다. 잔액이 다음 호출을 감당하지 못하면
`402`를 반환하며, 재시도로는 해결되지 않습니다. **대시보드 > 잔액**에서 충전하세요.