> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moove.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Moove API Keys

> Moove API용 범위가 지정된 API 키를 만들고, 한 번 복사하고, 다 쓰면 영구적으로 폐기하세요.

키를 만들고, 한 번 복사하고, Moove API를 호출하는 데 쓰세요.

<Info>
  **웹 전용**, [moove.xyz/dashboard/api-keys](https://www.moove.xyz/dashboard/api-keys)에서. 모바일 대응 화면은 없습니다.
</Info>

## API 키는 어떻게 만드나요?

<Steps>
  <Step title="관리 → API 키 열기">
    웹 대시보드에서.
  </Step>

  <Step title="이름 붙이기">
    6개월 뒤에도 알아볼 수 있는 이름 — 어떤 서비스나 환경을 위한 키인지.
  </Step>

  <Step title="에이전트 고르기">
    실제로 존재하는 것은 **Moove Receive Agent**입니다. 그 에이전트에 필요한 범위로 펼쳐집니다.
  </Step>

  <Step title="키 복사하기">
    <Warning>
      평문 키는 생성 시점에 **한 번만** 표시됩니다. 지금 복사해 시크릿 매니저에 보관하세요. 복사하지 않고 대화상자를 닫으면 그 키는 쓸 수 없으니 새로 만들어야 합니다.
    </Warning>
  </Step>
</Steps>

기본 URL은 `https://api.moove.xyz`입니다.

## 원시 범위가 아니라 Moove 에이전트

권한 문자열이 아니라 **에이전트**를 고릅니다. "Moove Receive Agent"는 판매자가 이해할 수 있는 단위이고, `payment_link:create`는 그렇지 않습니다.

| 에이전트                    | 상태       | 부여하는 범위                                    |
| ----------------------- | -------- | ------------------------------------------ |
| **Moove Receive Agent** | **운영 중** | `payment_link:create`, `payment_link:read` |
| Moove Send Agent        | 곧 출시     | —                                          |
| Moove Swap Agent        | 곧 출시     | —                                          |
| Moove Ramp Agent        | 곧 출시     | —                                          |

곧 출시되는 세 에이전트는 비활성 상태로 표시됩니다. 그중 하나를 선택하면 아무 권한도 없는 키가 만들어지므로, 선택기가 이를 허용하지 않습니다.

## API 키가 할 수 있는 것과 할 수 없는 것

<Note>
  키는 **당신의 축소판**입니다. 당신의 계정으로 동작하며, 당신이 할 수 있는 일의 일부만 할 수 있습니다.

  **자금을 옮기는 엔드포인트는 없습니다.** 결제 링크는 언제나 당신의 기본 지갑으로, 그 지갑의 토큰으로 정산됩니다 — 호출하는 쪽이 목적지를 지정할 수 없습니다. 유출된 키는 *당신에게* 지급되는 요청을 만들 수 있을 뿐, 다른 누구에게도 지급할 수 없습니다.
</Note>

키는 또 다른 키를 만들 수도 없습니다. 키 관리는 세션 인증으로만 가능하므로, 탈취된 키가 스스로 권한을 키울 수 없습니다.

## 키를 어떻게 안전하게 지키나요?

<Warning>
  * 시크릿 매니저나 환경 변수에 보관하세요. 소스 관리에는 절대 넣지 마세요.
  * 프롬프트, 채팅, 이슈, 스크린샷에 붙여넣지 마세요.
  * 서비스마다 별도의 키를 쓰세요. 하나를 폐기해도 나머지가 멈추지 않습니다.
  * 조금이라도 미심쩍은 키는 폐기하세요. 새로 만드는 데는 몇 초면 됩니다.
</Warning>

## 키는 몇 개까지 가질 수 있나요?

계정당 **활성 키 10개**까지입니다. 열한 번째를 만들면 요청이 `TOO_MANY_API_KEYS`로 거부되니, 더 쓰지 않는 키를 먼저 폐기하세요.

<Tip>
  이 상한은 배포 단위가 아니라 연동 단위로 키의 범위를 잡으라는 신호입니다. 실제로 운영하는 서비스마다 키 하나가 이해하기 쉽고, 무언가 바뀌었을 때 폐기하기도 쉽습니다.
</Tip>

## 키는 어떻게 폐기하나요?

<Steps>
  <Step title="키 메뉴 열기">
    **관리 → API 키**에서 해당 키 행의 **…** 메뉴를 열고 **해지**를 고르세요.
  </Step>

  <Step title="확인하기">
    확인하려면 **해지**를 한 번 더 클릭하세요. 키는 즉시 작동을 멈춥니다.
  </Step>
</Steps>

<Warning>
  **폐기는 영구적입니다.** 되돌리는 방법은 없습니다. 평문은 애초에 저장된 적이 없으므로, 기록을 복원하더라도 폐기된 키는 다시 쓰일 수 없습니다. 새 키를 발급하세요.
</Warning>

## 키는 어떻게 사용하나요?

모든 요청의 `X-API-Key` 헤더에 담아 보내세요.

```bash theme={null}
curl -sS -X POST "https://api.moove.xyz/v1/payment-link" \
  -H "X-API-Key: $MOOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toAmount": "49.99" }'
```

[인증 →](/api-reference/authentication)

## 첫 호출 전에

API는 결제를 받을 수 없는 계정을 위해서는 링크를 만들지 않습니다. [Moove 핸들](/ko-kr/brand/moove-handle)을 확보하고 [정산 토큰](/ko-kr/concepts/settlement-and-auto-routing)이 설정된 기본 지갑을 지정했는지 확인하세요 — 그러지 않으면 `409`가 돌아옵니다.

## 다음에 읽을 것

<CardGroup cols={3}>
  <Card title="인증" icon="lock" href="/api-reference/authentication">
    헤더가 작동하는 방식.
  </Card>

  <Card title="Moove Agentic Payments" icon="sparkles" href="/ko-kr/transact/moove-agentic-payments">
    AI 도구가 연동을 대신하게 하기.
  </Card>

  <Card title="Moove Payment Links API" icon="link" href="/api-reference/moove-receive/moove-payment-links">
    엔드포인트 전체.
  </Card>
</CardGroup>

범위가 정해지고, 폐기할 수 있고, 당신의 것입니다. 당신의 돈. 당신의 선택.