# 시작하기

> 계정 API 키를 만들고 첫 요청을 보냅니다.

## 1. 계정 만들기

[account.gujo.ai](https://account.gujo.ai) 에서 가입하고 로그인합니다. 키는 그 계정이 가진 이용권과 구독만 봅니다.

## 2. API 키 만들기

[account.gujo.ai/settings/developer](https://account.gujo.ai/settings/developer)(계정의 **개발자 설정** 화면)의 **API 키** 칸에서 키를 만듭니다.

1. 이름을 적습니다. 어느 기기나 도구에서 쓰는 키인지 알아볼 수 있으면 됩니다.
2. 능력을 고릅니다. 처음에는 `products.read`·`mcp.read`·`device.install` 이 골라져 있고, 이대로 두면 라이브러리 조회와 MCP 연결을 모두 할 수 있습니다. 주문이나 구독도 읽으려면 `orders.read`·`subscriptions.read` 를 더합니다.
3. 필요하면 만료일을 정합니다. 비워 두면 폐기할 때까지 쓸 수 있습니다.
4. **키 발급**을 누릅니다. 키 값은 이때 한 번만 보이므로 바로 비밀 저장소나 환경 변수에 옮깁니다.

능력의 뜻, 키 개수 한도, 폐기는 [인증과 API 키](auth.md)에 있습니다.

```bash
export GUJO_API_KEY="발급된 키"
```

키는 명령 인자나 주소에 적지 않습니다. 셸 기록과 서버 로그에 남기 때문입니다.

## 3. 첫 요청 보내기

이 키로 쓸 수 있는 상품 목록을 받아 봅니다.

```bash
curl https://api.gujo.ai/api/library \
  -H "Authorization: Bearer $GUJO_API_KEY"
```

성공하면 200 과 함께 쓸 수 있는 상품이 숫자 id 로 옵니다. 상품마다 배달 정보와 설정 진행 상태도 함께 옵니다. 응답의 모양은 [API 참조](api-reference.md)의 `library` 항목에 있습니다.

실패하면 본문은 `{"message": "...", "error": "<코드>"}` 꼴입니다.

| 상태 | `error` | 확인할 것 |
|---|---|---|
| 401 | `missing_api_key` | `Authorization` 머리글이 빠졌습니다 |
| 401 | `invalid_api_key` | 키가 틀렸거나 폐기·만료됐습니다 |
| 403 | `missing_api_key_ability` | 키에 `products.read` 능력이 없습니다 |

## 4. 에이전트 연결하기

에이전트는 MCP 로 같은 일을 할 수 있습니다. 주소는 `https://api.gujo.ai/api/mcp` 입니다. Claude Code·Cursor 같은 클라이언트에는 키 없이 주소만 넣고 브라우저에서 로그인해 연결합니다. CI 처럼 로그인할 수 없는 곳에서는 `mcp.read` 능력이 있는 이 키를 씁니다. 클라이언트별 설치 버튼과 설정은 [MCP 연결하기](mcp/index.md)에 있습니다.

## 다음에 볼 것

- 산 제품을 터미널에서 설치하려면 [gujoctl](gujoctl.md)을 봅니다.
- 부를 수 있는 문 전체는 [API 참조](api-reference.md)에 있습니다.