> ## 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 키 또는 JWT 토큰을 사용하여 AgentWallex API에 인증하는 방법을 설명합니다.

## 인증 방법

AgentWallex는 두 가지 인증 방법을 지원합니다:

| 방법               | 헤더                             | 사용 사례               |
| ---------------- | ------------------------------ | ------------------- |
| API Key          | `X-API-Key: awx_...`           | SDK 및 서버 간 통합       |
| JWT Bearer Token | `Authorization: Bearer eyJ...` | 웹 앱, OAuth, 대시보드 세션 |

## API 키 인증

API 키는 서버 측 및 SDK 통합에 권장되는 방식입니다. 모든 키는 `awx_` 접두사로 시작합니다.

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/agents \
  -H "X-API-Key: awx_your_api_key"
```

<Warning>
  클라이언트 측 코드, 공개 저장소 또는 로그에 API 키를 노출하지 마세요. 항상 환경 변수에서 로드하세요.
</Warning>

### 환경 변수

API 키를 환경 변수로 저장하세요:

<CodeGroup>
  ```bash .env theme={null}
  AGENTWALLEX_API_KEY=awx_your_api_key
  ```

  ```typescript TypeScript theme={null}
  import { AgentWallex } from "@agentwallex/sdk";

  const aw = new AgentWallex({
    apiKey: process.env.AGENTWALLEX_API_KEY!,
  });
  ```

  ```python Python theme={null}
  import os
  from agentwallex import AgentWallex

  aw = AgentWallex(api_key=os.environ["AGENTWALLEX_API_KEY"])
  ```
</CodeGroup>

## JWT Bearer Token 인증

웹 애플리케이션 및 OAuth 플로우의 경우 JWT 베어러 토큰을 사용합니다. 토큰은 Google OAuth 플로우를 통해 획득합니다:

<Steps>
  <Step title="OAuth 플로우 시작">
    사용자를 Google OAuth 엔드포인트로 리다이렉트합니다:

    ```
    GET /auth/google/redirect
    ```
  </Step>

  <Step title="콜백 처리">
    인증 후 Google이 일회성 코드와 함께 콜백 URL로 리다이렉트합니다:

    ```
    GET /auth/google/callback
    ```
  </Step>

  <Step title="토큰 교환">
    일회성 코드를 액세스 토큰 및 리프레시 토큰으로 교환합니다:

    ```bash theme={null}
    curl -X POST https://api.agentwallex.com/api/v1/auth/exchange \
      -H "Content-Type: application/json" \
      -d '{"exchange_code": "one_time_code"}'
    ```
  </Step>

  <Step title="액세스 토큰 사용">
    `Authorization` 헤더에 액세스 토큰을 포함합니다:

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

### 토큰 갱신

액세스 토큰은 만료됩니다. 리프레시 토큰을 사용하여 새 액세스 토큰을 획득하세요:

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'
```

### 로그아웃

현재 세션을 무효화합니다:

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

## 보안 모범 사례

<Tip>
  통합을 안전하게 유지하려면 다음 사항을 따르세요.
</Tip>

* **환경 변수 사용** — 소스 코드에 API 키를 하드코딩하지 마세요.
* **키를 정기적으로 교체** — 최소 90일마다 API 키를 교체하세요. 교체 방법은 [API 키](/ko/introduction/api-keys)를 참조하세요.
* **필요한 최소 범위 사용** — 환경별(샌드박스 vs. 프로덕션)로 별도의 API 키를 생성하세요.
* **IP 허용 목록 활성화** — Growth 및 Enterprise 플랜에서 알려진 IP로 API 접근을 제한할 수 있습니다.
* **감사 로그 모니터링** — 대시보드 또는 `GET /audit-logs`를 통해 인증 이벤트를 검토하세요.
* **개발에는 샌드박스 사용** — 프로덕션 키나 실제 자금으로 테스트하지 마세요.