# 인증 (Authentication)

GENCY OpenAPI는 두 가지 인증 방식을 지원합니다.

> **MCP 클라이언트(@gency-ai/gency-mcp)는 OAuth-only.** AI 어시스턴트에서 자연어로 GENCY 를 사용한다면 `gency-mcp login` 한 번이면 충분합니다. 아래 두 방식은 **자신의 서버/스크립트에서 REST API 를 직접 호출**할 때 선택합니다.

## API Key 인증 (REST API 직접 호출용)

개발자 포털에서 앱을 생성하면 API Key가 발급됩니다(INTERNAL 앱만 가능). 자신의 통합 코드에서 모든 요청에 `X-API-Key` 헤더를 포함하세요. gency-mcp 에는 절대 넣지 마세요 — MCP 는 API Key 를 사용하지 않습니다.

```bash
curl -H "X-API-Key: gency_ak_your_key_here" \
  https://openapi.gency.ai/openapi/v1/teams/me
```

## OAuth 2.0 Bearer Token 인증

OAuth 2.0 Authorization Code + PKCE 플로우로 발급받은 access token을 사용합니다. gency-mcp 가 사용자 PC 에서 사용하는 방식과 동일하며, 자신의 사용자에게 GENCY 를 위임 인증시키는 자체 앱에서도 사용합니다.

```bash
curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://openapi.gency.ai/openapi/v1/teams/me
```

### OAuth 토큰 발급 과정

1. `GET /oauth/authorize` — 인가 코드 요청 (PKCE 지원)
2. 사용자 로그인 및 스코프 동의
3. `POST /oauth/token` — 인가 코드로 access token 발급
4. access token 만료 시 `POST /oauth/token`에 `grant_type=refresh_token`으로 갱신

### 사용 가능한 스코프

| 스코프          | 설명             |
| --------------- | ---------------- |
| `product:read`  | 상품 조회        |
| `product:write` | 상품 생성/수정   |
| `team:read`     | 팀 정보 조회     |
| `team:write`    | 팀 정보 수정     |
| `user:read`     | 사용자 정보 조회 |

## 응답 형식

모든 OpenAPI 엔드포인트의 응답은 다음 형태로 감싸져 있습니다:

```json
{
  "data": { ... }
}
```