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

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt)

`gateway.apinoa.com`으로 가는 모든 요청은 `x-api-key` 헤더에 API 키를 담습니다. 다른 인증 방법은 없으며,
키 없는 요청은 처리하지 않습니다.

## 키 발급

**대시보드 > API 키**에서 키를 만듭니다. 전체 키는 생성할 때 **한 번만** 표시되므로, 그때 복사해
안전한 곳에 보관하세요. 잃어버리면 새 키를 만들고 이전 키를 폐기합니다.

대시보드를 열지 않고 터미널에서 받을 수도 있습니다. 프로젝트 디렉터리에서 실행하세요.

```bash
npx apinoa-mcp login
```

페이지 주소 `https://api.apinoa.com/oauth/device`와 `BCDF-GHJK` 같은 8자리 코드가 출력되고, 대화형 터미널이면
페이지가 자동으로 열립니다. 그 페이지에서 apinoa에 로그인하고(계정이 없으면 새로 만들고) 코드를 입력해 승인하세요.
그러면 현재 디렉터리의 `.env`에 `APINOA_API_KEY=<key>`가 기록됩니다(다른 파일에 쓰려면 `--out <path>`).
`APINOA_API_KEY` 줄이 이미 있으면 그 줄만 바꾸고 나머지 내용은 그대로 두며, `.env`가 git ignore 대상이 아니면
경고합니다. 전체 키는 화면에 출력하지 않습니다.

이렇게 받은 키는 `apinoa_mcp_`로 시작하고 90일 뒤 만료됩니다. 만료되면 `npx apinoa-mcp login`을 다시 실행하세요.
이 키도 **대시보드 > API 키**에 표시되며, 다른 키처럼 폐기할 수 있습니다. 이렇게 키가 만들어질 때마다 이메일로
알려 드립니다. CLI 키는 계정당 다섯 개까지 유지되며, 여섯 번째 로그인은 가장 오래된 키를 폐기하고 어떤 키인지 알려 줍니다. 이 방법이나
[호스팅 MCP 서버](/docs/sdks#호스팅-설치-없이) 로그인으로 처음 받는 키에는 **$0.10 평가용 크레딧**이 지급됩니다(계정당
한 번). 이미 무료 크레딧을 받은 계정에는 지급되지 않습니다.

**코드는 방금 자신의 터미널에서 직접 시작한 것만 입력하세요.** 누군가 코드를 보내며 입력해 달라고 한다면, 당신의
계정에 접근하게 해 달라는 요청입니다.

키는 여러 개를 동시에 가질 수 있으며, 이를 이용해 중단 없이 키를 교체합니다. 새 키를 만들고,
트래픽을 새 키로 옮긴 뒤, 이전 키를 폐기하세요.

## 모든 요청에 보내기

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const res = await fetch("https://gateway.apinoa.com/v1/amazon/search?query=wool+socks", {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/amazon/search",
    params={"query": "wool socks"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
```

## 서버에만 보관하기

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

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

## 인증에 실패하면

| 상태 | 코드 | 의미 |
|---|---|---|
| 401 | `UNAUTHORIZED` | `x-api-key` 헤더가 없거나, 키가 유효하지 않거나 폐기되었습니다. |
| 402 | `INSUFFICIENT_BALANCE` | 키는 유효하지만 잔액이 이 호출 비용에 모자랍니다. |
| 403 | `ACCOUNT_SUSPENDED` | 계정이 정지되어 그 계정의 모든 키가 거부됩니다. 고객 지원에 문의하세요. |

각 호출은 [가격 페이지](/pricing)의 요율로 잔액에서 차감됩니다. 잔액이 다음 호출 비용에
모자라면 API는 `402`로 응답하며, 다시 시도해도 해결되지 않습니다.
**대시보드 > 잔액**에서 충전하세요.