# API

새로온 API의 인증은 두 종류의 키로 이루어집니다. 대부분의 작업은 CLI와 자동 주입되는 SDK가 대신 처리하므로, 키를 직접 다룰 일은 서버 간 연동이나 커스텀 클라이언트를 만들 때입니다.

- API 베이스: `https://api.saeroon.com`
- 키 발급·관리: [https://developers.saeroon.com/keys](https://developers.saeroon.com/keys)

## 두 가지 키

| 키 | 접두사 | 성격 | 인증 헤더 |
|---|---|---|---|
| 비밀 키(Secret) | `sk_live_` | 서버 전용. 노출 금지 | `Authorization: Bearer sk_live_…` |
| 공개 키(Publishable) | `pk_live_` | 브라우저 노출 가능 | `X-Saeroon-Pk: pk_live_…` |

비밀 키는 CLI 로그인·배포·서버 간 호출처럼 신뢰된 환경에서만 씁니다. 공개 키는 정적 사이트에 주입되어 회원·게시판 SDK가 사이트(테넌트)를 해석하는 데 쓰입니다 — 노출을 전제로 설계된 키라 안전합니다. (쇼핑 SDK는 공개 키가 아니라 `data-site-slug` 로 사이트를 해석합니다.)

```bash
# 서버에서 비밀 키로 호출
curl -H "Authorization: Bearer sk_live_XXXX" https://api.saeroon.com/...

# 브라우저에서 공개 키로 호출
curl -H "X-Saeroon-Pk: pk_live_XXXX" https://api.saeroon.com/...
```

## 어디에 어떤 키가 쓰이나

- **CLI**: `login` 시 비밀 키를 저장하고, `deploy` 등은 그 키로 인증합니다.
- **정적 사이트 SDK**: `deploy --pk pk_live_…` 로 넘긴 공개 키가 페이지에 주입되어, 브라우저에서 회원·게시판 API를 호출할 때 쓰입니다. 공개 키는 사이트를 배포한 뒤 [키 관리](https://developers.saeroon.com/keys)에서 사이트별로 발급합니다. **넘기지 않으면 배포는 성공하지만 라이브에서 로그인·글쓰기가 조용히 실패합니다.** 쇼핑 SDK는 사이트 slug 로 스코프됩니다.
- **서버 간 연동**: 비밀 키를 `Authorization: Bearer` 로 보냅니다.

## 인증 실패

키가 없거나 잘못되면 응답은 `401 Unauthorized` 입니다. 이 경우 [키 관리](https://developers.saeroon.com/keys)에서 키를 확인하거나 재발급하세요.

## 기능별 API

각 기능이 브라우저에서 쓰는 공개 API는 배포 시 자동 연결됩니다. 직접 다룰 일은 거의 없지만, 동작 방식은 기능 문서에 정리되어 있습니다.

- [Forms](/docs/forms) · [Members](/docs/members) · [Boards](/docs/boards) · [Shop](/docs/shop)

CLI 명령 전체는 [CLI 레퍼런스](/docs/cli)를 참고하세요.