# 자격증명 발급 가이드

이 가이드는 **자신의 서버/앱 코드에서 GENCY REST API 를 직접 호출**할 때 필요한 자격증명을 발급·관리하는 절차입니다.

> **MCP만 쓸 거면 이 단계 불필요.** [@gency-ai/gency-mcp](mcp-setup.md) 는 OAuth 인증만 사용하며 공식 MCP 공용 OAuth 앱이 내장되어 있어 `gency-mcp login` 한 번 동의로 사용할 수 있습니다. **API Key는 MCP 에서 사용되지 않으니** 아래 절차는 자신의 코드에서 REST API 를 직접 호출하거나 자체 OAuth 앱을 만들 때만 따르세요.

## 인증 방식 요약

| 사용처                                | 인증 방식             | 자격증명                            |
| ------------------------------------- | --------------------- | ----------------------------------- |
| gency-mcp (Claude / Cursor / VS Code) | OAuth 2.0 (PKCE)      | 내장 공용 client — 발급 불필요      |
| 자체 OAuth 앱으로 사용자 위임 인증    | OAuth 2.0 (PKCE)      | 직접 발급한 Client ID/Secret        |
| 자기 서버에서 자기 데이터만 호출      | API Key (`X-API-Key`) | 직접 발급한 API Key                 |

## 1단계: 개발자 포털 로그인

1. [developers.gency.ai](https://developers.gency.ai)에 접속
2. 이메일/비밀번호 또는 Google 계정으로 로그인

## 2단계: Application 생성

1. 왼쪽 사이드바에서 **앱** 메뉴로 이동
2. **앱 추가하기** 클릭
3. **앱 이름**을 입력합니다 (예: "내 쇼핑몰 연동"). 앱 로고는 선택입니다
4. **추가하기**를 누르면 앱 상세 화면으로 이동합니다

> 생성 화면에는 이름과 로고만 있습니다. Redirect URI 와 스코프는 앱을 만든 **다음에** 각각 3단계·4단계에서 설정합니다.

## 3단계: Redirect URI 등록 (OAuth 사용 시)

사용자 위임 OAuth 를 쓸 때만 필요합니다. API Key 로 자기 데이터만 호출한다면 건너뛰어도 됩니다.

1. 앱 상세 화면의 **Redirect URI** 항목에서 콜백 URL 을 추가 (최대 5개)
2. **저장하기** 클릭

## 4단계: 권한(스코프) 저장 — 건너뛰면 모든 호출이 실패합니다

**앱은 스코프가 하나도 없는 상태로 생성됩니다.** 이 단계를 지나치면 API Key 가 정상 발급·활성화되어도 모든 호출이 `400 Insufficient scope` 로 실패합니다.

1. **앱** 목록에서 해당 앱 행의 **권한 관리** 클릭
2. 드롭다운에서 필요한 스코프를 선택
3. **저장하기** 클릭

선택할 수 있는 스코프는 다음과 같습니다.

| 스코프          | 설명               |
| --------------- | ------------------ |
| `product:read`  | 상품 목록 조회     |
| `product:write` | 상품 생성/수정/삭제 |
| `team:read`     | 팀 조회            |
| `team:write`    | 팀 수정/관리       |
| `user:read`     | 사용자 조회        |

## 5단계: 자격증명 확인과 API Key 활성화

앱 상세 화면에서 다음 자격증명을 확인할 수 있습니다.

| 자격증명          | 형식             | 용도                                        |
| ----------------- | ---------------- | ------------------------------------------- |
| **Client ID**     | `gency_client_…` | OAuth 2.0 인증 시 앱 식별자                 |
| **Client Secret** | `gency_…`        | OAuth 2.0 토큰 발급 시 사용 (안전하게 보관) |
| **API Key**       | `gency_key_…`    | 간편 인증 키 (X-API-Key 헤더로 전송)        |

API Key 는 **비활성 상태로 시작합니다.** `X-API-Key` 인증을 쓰려면 반드시 켜야 합니다.

1. 앱 상세 페이지의 API Key 섹션에서 토글을 **활성**으로 전환
2. **복사하기**로 키를 가져와 `X-API-Key` 헤더로 사용:

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

> **보안 주의**: Client Secret 과 API Key 는 앱 상세 화면에서 언제든 다시 확인할 수 있습니다(화면에는 가려져 보이지만 **복사하기**는 실제 값을 복사합니다). 그만큼 유출 시 영향이 크므로, 노출이 의심되면 **재생성하기**로 즉시 교체하세요. 재생성하면 이전 값은 그 즉시 무효가 되어 기존 연동이 끊깁니다.
>
> 앱을 삭제하면 그 앱의 API Key 도 곧바로 무효가 됩니다.
>
> **MCP에는 절대 넣지 마세요.** gency-mcp 는 API Key 를 사용하지 않으며, 환경변수나 파일로 주입해도 무시됩니다. MCP 는 `gency-mcp login` 으로 OAuth 토큰을 사용합니다.