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

# API 키

> AgentWallex 통합을 위한 API 키를 생성, 관리, 교체합니다.

## 개요

API 키는 서버 측 애플리케이션을 AgentWallex API로 인증합니다. 각 키는 `awx_` 접두사로 시작하며 계정에 연결됩니다.

## API 키 생성

대시보드 또는 REST API(JWT 인증 필요)를 통해 API 키를 생성합니다:

### 대시보드를 통한 생성

1. [AgentWallex 대시보드](https://app.agentwallex.com)에 로그인합니다.
2. **Settings > API Keys**로 이동합니다.
3. **Create API Key**를 클릭합니다.
4. 키에 설명이 포함된 이름을 지정합니다 (예: `production-backend`, `staging-ci`).
5. 키를 복사하고 안전하게 저장합니다 — 한 번만 표시됩니다.

### API를 통한 생성

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production-backend"}'
```

<Warning>
  전체 API 키는 생성 시 한 번만 반환됩니다. 즉시 안전한 시크릿 관리자에 저장하세요.
</Warning>

## API 키 목록 조회

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOi..."
```

응답에는 키 메타데이터가 포함되지만 전체 키 값은 절대 포함되지 않습니다:

```json theme={null}
{
  "data": [
    {
      "id": "key_abc123",
      "name": "production-backend",
      "prefix": "awx_...x4f2",
      "created_at": "2025-06-01T10:00:00Z",
      "last_used_at": "2025-06-15T14:30:00Z"
    }
  ]
}
```

## API 키 교체

<Steps>
  <Step title="새 키 생성">
    대시보드 또는 API를 통해 새 API 키를 생성합니다.
  </Step>

  <Step title="애플리케이션 업데이트">
    새 키를 애플리케이션의 환경 변수에 배포합니다.
  </Step>

  <Step title="새 키 동작 확인">
    새 키로 API 호출이 성공하는지 확인합니다.
  </Step>

  <Step title="이전 키 삭제">
    무단 접근을 방지하기 위해 이전 키를 제거합니다:

    ```bash theme={null}
    curl -X DELETE https://api.agentwallex.com/api/v1/api-keys/key_abc123 \
      -H "Authorization: Bearer eyJhbGciOi..."
    ```
  </Step>
</Steps>

<Tip>
  최소 90일마다 API 키를 교체하세요. 캘린더 알림을 설정하거나 CI/CD 파이프라인으로 교체를 자동화하세요.
</Tip>

## 속도 제한

API 속도 제한은 플랜 등급에 따라 달라집니다:

| 플랜         | 요청/분 | 요청/일    | 동시 연결 |
| ---------- | ---- | ------- | ----- |
| Starter    | 60   | 10,000  | 5     |
| Growth     | 300  | 100,000 | 25    |
| Enterprise | 커스텀  | 커스텀     | 커스텀   |

속도 제한을 초과하면 API는 `Retry-After` 헤더와 함께 `429 Too Many Requests` 응답을 반환합니다:

```json theme={null}
{
  "code": "rate_limit_exceeded",
  "type": "rate_limit_error",
  "message": "Rate limit exceeded. Retry after 30 seconds."
}
```

<Note>
  속도 제한은 API 키별로 적용됩니다. 더 높은 한도가 필요한 경우 AgentWallex 팀에 문의하거나 플랜을 업그레이드하세요.
</Note>

## 모범 사례

* **환경별 하나의 키** — 개발, 스테이징, 프로덕션에 별도의 키를 사용하세요.
* **키 이름을 설명적으로** — 환경과 서비스 이름을 포함하세요 (예: `prod-payment-service`).
* **사용량 모니터링** — `last_used_at`을 확인하여 삭제해야 할 미사용 키를 식별하세요.
* **키를 공유하지 마세요** — 각 팀 멤버 또는 서비스는 자체 키를 가져야 합니다.
* **시크릿 관리자 사용** — 디스크의 `.env` 파일 대신 AWS Secrets Manager, HashiCorp Vault 또는 유사한 도구에 키를 저장하세요.