---
title: 시작하기
description: API 키 발급, 환경변수 설정, 패키지 설치, 첫 콘텐츠 조회
---

# 시작하기

## 1. API 키 발급

1. 어드민(`admin.roottale.com`) 로그인
2. **설정 > 사이트 연결 키** 메뉴로 이동
3. 새 키 발급 — 권한 선택 (괄호 안은 화면에 보이는 이름):
   - **read** — "읽기" (기본): 공개 콘텐츠와 관리 API의
     초안·예약·비공개 글, 미디어 목록을 조회할 수 있음.
     **완전한 읽기 전용은 아닙니다** — 상담 게시판
     글 작성(`POST /v1/cms/public/inquiries`)이 이 권한으로 됩니다(사이트의
     상담 폼이 동작하려면 필요). 기존 글·미디어·설정을 고치거나 지우지는 못함
   - **read_write** — "읽기 + 쓰기": 위에 더해 글 작성·수정·**발행·발행 취소·
     영구 삭제**, 미디어 업로드·**삭제**, 카테고리/태그 생성·**삭제**(딸린
     연결까지 cascade). 유출 시 콘텐츠가 지워질 수 있는 권한입니다
   - **read_write_settings** — "읽기 + 쓰기 + 설정 변경": 위에 더해
     **사이트 설정 쓰기**(사업장 정보·상단 메뉴)와, 수동 갱신 API로
     **설정 저장 신호(`theme.updated`) 보내기**. 뒤엣것은 사이트의 모든 페이지를
     다시 만들게 하는 신호라 글쓰기 권한과 나눠 두었습니다. 어드민 화면 대신
     외부 도구가 가게 이름·주소·전화번호·메뉴를 고쳐야 할 때만 선택하세요.
     쓰는 방법은 [HTTP API 레퍼런스의 "설정 쓰기 API"](./api-reference.md#설정-쓰기-api)
4. 발급된 키(`rtlk_cust_` + 24자)는 **발급 직후 1회만 평문 표시**됩니다. 바로
   복사해 환경변수에 저장하세요.

발급된 뒤에는 키 목록에서 각 키의 권한 이름과 **실제 scope 전체**를 확인할 수
있습니다("이 키의 권한 자세히"). 설정 변경이 가능하거나 화면이 모르는 scope가
섞인 키는 눈에 띄게 표시됩니다.

키는 사이트 단위로 스코프되어(site-scoped) 해당 사이트의 콘텐츠·웹훅 검증에만
사용됩니다.

권한별 scope는 다음과 같습니다. 넓은 권한은 좁은 권한을 그대로 포함합니다.

| 권한 | scope |
|---|---|
| `read` | `cms:read` |
| `read_write` | `cms:read` `cms:write` `post:draft:write` `post:publish` `media:write` `taxonomies:write` |
| `read_write_settings` | `read_write` + `settings:write` |

> `cms:read`라는 이름과 달리 이 scope 하나로 상담 게시판 글이 **생성**됩니다.
> "최소 권한 = 아무것도 못 바꿈"으로 읽지 마세요.

`settings:write`는 **새로 발급하는 키에만** 붙습니다. 이미 쓰고 있는
`read_write` 키는 그대로 두어도 동작이 달라지지 않고, 설정 쓰기 권한이
저절로 생기지도 않습니다.

### 발급한 뒤에 권한을 바꾸려면 — 새 키로 교체

발급된 키의 권한은 **나중에 바꿀 수 없습니다.** 예를 들어 `read_write` 키를
쓰다가 설정 쓰기가 필요해졌다면, 그 키에 권한을 더하는 것이 아니라 새 키를
발급해 교체합니다. 순서를 지키면 서비스가 끊기지 않습니다.

1. 어드민 **설정 > 사이트 연결 키**에서 원하는 권한으로 **새 키를 발급**합니다.
   이름은 교체 대상과 구분되게 적으세요(예: `운영 서버 2026-07`). 목록에 붙는
   권한 이름으로 어떤 키를 교체해야 하는지 찾을 수 있습니다.
2. 배포 환경의 `ROOTTALE_API_KEY`를 새 키로 바꾸고 **재배포**합니다.
   (환경변수만 바꾸고 재배포하지 않으면 옛 키가 계속 쓰입니다.)
3. 사이트가 정상 동작하는지 확인합니다 — 글 목록이 보이는지, 자동화가
   `401 invalid_key` 없이 도는지.
4. 목록의 **최근 사용**(날짜 + 시각)이 교체 시점 이후로 갱신되지 않는지 확인한 뒤
   삭제합니다. 판정 기준은 **그 키의 정상 호출 주기를 한 번 넘길 때까지 관찰**
   입니다 — 하루 한 번 도는 배치라면 하루, ISR 재검증이 30분이면 30분. 배포가
   여러 곳(프리뷰·스테이징·사내 도구)이면 전부 교체됐는지 함께 봅니다.
   옛 키를 먼저 지우면 그 사이 요청이 `401 invalid_key`로 실패합니다.

같은 절차를 키 유출이 의심될 때도 씁니다. 다만 그때는 순서를 뒤집어, 옛 키를
먼저 삭제하고 새 키로 교체하세요 — 잠깐의 중단보다 유출된 키가 살아 있는 쪽이
위험합니다.

## 2. 환경변수

```bash
# .env.local (Next.js) 또는 배포 플랫폼의 환경변수 — 반드시 서버 전용
ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx

# (선택) API 베이스 오버라이드 — 기본값 https://api.roottale.com 이면 생략
# ROOTTALE_API_BASE=https://api.roottale.com

# 사이트 정식 도메인 (RSS/sitemap/canonical 생성용)
NEXT_PUBLIC_SITE_URL=https://example.com

# (선택) RootTale 관리자에서 IndexNow를 켰을 때 발급된 검증 키
INDEXNOW_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**중요**: `ROOTTALE_API_KEY`는 절대 `NEXT_PUBLIC_*` 접두를 붙이지 마세요.
브라우저로 노출되면 누구나 그 키로 API를 호출할 수 있습니다.
`@roottale/cms-client`는 브라우저에서 실행되면 의도적으로 에러를 던집니다.

## 3. 패키지 설치

```bash
# Next.js 사이트
npm install @roottale/cms-client @roottale/cms-renderer-next
# 또는
pnpm add @roottale/cms-client @roottale/cms-renderer-next
```

요구사항: Node ≥ 18.18, React 19, Next.js 14+ (renderer-next 사용 시).

사이트 이미지에는 `@roottale/cms-media/react`의 `RootTaleImage`를 사용합니다.
이는 공용 네이티브 img 컴포넌트로, CF Images에서 반응형 이미지를 직접 전달합니다.
새 export는 해당 변경을 포함한 패키지 릴리스 후 사용할 수 있습니다.

```tsx
import { RootTaleImage } from "@roottale/cms-media/react";

<RootTaleImage src={coverUrl} alt="대표 이미지" width={800} height={556}
  sizes="(max-width: 880px) calc(100vw - 36px), 840px" />
```

이미지 사용 사이트는 `@roottale/cms-media`를 직접 의존성으로 설치합니다.
CF Flexible variants가 필요하며 `next/image`·Vercel 변환은 사용하지 않습니다.
등록된 R2·로컬 자산의 매핑은 사이트에 두고 `@roottale/cms-media/delivery`의
`createImageDelivery`로 `imageAttributes`·`fallbackSrc`만 계산합니다.
CMS 저장 주소와 원본은 유지합니다. 정적 import·ref·fill·priority도 지원합니다.
기존 `CfImage`·default export는 호환성을 유지합니다.

분류 선택·공개 콘텐츠 정책 API는 SDK **0.69.0부터** 제공합니다. 이 API를 직접
사용하는 사이트는 `@roottale/cms-core`도 직접 의존성으로 설치하고 세 패키지의
버전을 맞추세요.

```bash
pnpm add @roottale/cms-client@0.69.0 @roottale/cms-renderer-next@0.69.0 @roottale/cms-core@0.69.0
```

렌더러 스타일은 root layout에서 1회 import:

```ts
// app/layout.tsx
import "@roottale/cms-renderer-next/styles";
```

기본 본문은 720px 폭, 18px/1.7이며 768px 미만에서는 17px입니다.
글 제목은 데스크톱 44px/700/1.3, 모바일 28px/600/1.3입니다.
본문 H2/H3/H4는 데스크톱 32/24/20px, 모바일 22/20/18px입니다.
제목 아래 메타 정보 간격은 12px이며, H2 위 48px·아래 20px(모바일 16px),
H3 위 32px·아래 12px, H4 위 24px·아래 8px를 사용합니다.
Pretendard 가변 글꼴을 스타일 패키지에 포함합니다. 고객 글꼴은 `--rt-font-body`,
본문 폭은 `--rt-cms-measure`, 크기는 `--rt-cms-body-size`로 조정할 수 있습니다.
독립 본문은 `<div data-roottale-cms="body">`로 감싸면 같은 서식을 적용합니다.
CMS 편집 화면과 같은 간격을 쓰려면 이 범위의 글자 크기·행간·문단 여백을
사이트 CSS에서 다시 덮어쓰지 않습니다. 일반 문단 뒤는 16px, 목록 항목 사이는
8px입니다. 가져온 HTML은 `.rt-imported-html` 범위를 유지해 원문의 줄·빈 문단에
기본 여백을 중복으로 더하지 않습니다. 직접 지정한 문단 여백은 유지합니다.
목록의 `li` reset도 복원하며, 제목 안의 고정 크기 마크는 제목의 반응형 크기를
따릅니다. 일반 문단의 인라인 크기·행간 설정은 데스크톱에서 유지하고,
모바일에서는 본문과 소제목의 크기·행간을 따릅니다. 색상·강조는 유지됩니다.
본문 링크의 밑줄은 hover·active·키보드 focus 때 표시되고, 동작 줄이기 설정을 존중합니다.

본문 이미지는 읽기 폭까지 표시하며 `RootTaleBlogPost`에서는 클릭·Enter·Space로 확대됩니다.
확대 화면은 2배 확대, Esc·닫기, 원래 이미지로 포커스 복귀를 지원합니다.
이미 링크나 버튼인 이미지는 기존 동작을 유지하며, `data-no-zoom`으로 제외할 수 있습니다.
`data-fullsize-src`가 있으면 확대 이미지의 주소로 사용합니다.
독립 HTML·`RenderTiptap`에는 다음 클라이언트 경계를 감싸 사용합니다.

```tsx
import { RootTaleImageLightbox } from "@roottale/cms-renderer-next/image-lightbox";

<div data-roottale-cms="body">
  <RootTaleImageLightbox>
    <RenderTiptap doc={doc} />
  </RootTaleImageLightbox>
</div>
```

`tocPosition="sidebar"` 목차는 넓은 화면에서 고정됩니다.
모바일 목차는 접었을 때 기본 높이가 52px입니다.
`--rt-cms-scroll-offset`을 헤더 높이보다 크게 지정하세요. 조상 요소의
`overflow: hidden/auto`는 별도 스크롤 기준을 만들므로 화면 기준 sticky가 필요하면
불필요한 overflow를 제거하거나 `overflow: clip`을 사용하세요.

예시 코드는 `@/lib/blog` 형태의 import를 사용합니다 — `create-next-app` 기본
설정이면 그대로 동작하고, tsconfig를 직접 구성했다면 paths alias가 필요합니다:

```jsonc
// tsconfig.json > compilerOptions
"paths": { "@/*": ["./*"] }  // 또는 ["./src/*"]
```

## 4. 첫 조회 — 동작 확인

```ts
// 서버 컴포넌트, Route Handler, 또는 빌드 스크립트에서
import { fetchPosts } from "@roottale/cms-client/server";

const page = await fetchPosts({
  apiKey: process.env.ROOTTALE_API_KEY!,
  limit: 5,
  type: "post",
});
console.log(page.items.map((p) => p.slug));
```

응답이 비어 있다면 어드민에서 글이 **발행(published)** 상태인지 확인하세요.
공개 API는 발행된 콘텐츠만 반환합니다.

`401` 에러(`invalid_key`)면 키 값/환경변수 로딩을 확인하세요.

## 5. MCP로 전체 CMS 자동화

MCP 설정의 `ROOTTALE_API_KEY`에 `full_management` 키를 넣으면 모델·필드·항목·
노출·미디어 도구를 모두 쓸 수 있습니다. 글과 이미지만 관리한다면 기존
`read_write` 키로 충분합니다.

1. `getSiteKnowledge`로 브랜드 보이스와 금지어 확인
2. `uploadCmsMedia`로 썸네일 또는 본문 삽화 업로드
3. `createCmsPost`로 Tiptap JSON 초안 생성
4. 필요하면 `setCmsPostTerms`로 카테고리·태그 연결
5. 검토 후 `publishCmsPost`로 발행

정보 모델을 새로 자동화할 때는 `createCmsContentModel` →
`createCmsFieldGroup` → `createCmsPost(modelKey, fieldValues)` 순서로 진행합니다.
배너·팝업은 `listCmsExposureSlots`로 FRONT 계약을 먼저 읽고
`createCmsExposure` → `publishCmsExposure` 순서로 진행합니다.

썸네일은 업로드 응답의 `id`를 `featuredMediaId`에 넣습니다. 본문 삽화는
응답의 `url`을 Tiptap image 노드에 넣습니다.

```json
{
  "type": "image",
  "attrs": {
    "src": "https://media.example.com/tenant/site/image.webp",
    "alt": "서비스 진행 과정을 설명하는 삽화",
    "title": null
  }
}
```

안전한 기본값은 초안입니다. 사용자가 즉시 발행을 명시하지 않았다면
`createCmsPost`의 `publish`를 생략하고 검토 뒤 발행하세요.

## 6. CLI로 자동화

별도 전역 설치 없이 공개 MCP 패키지의 CLI 모드를 사용할 수 있습니다.

```bash
export ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx

npx -y @roottale/cms-mcp cli media upload ./thumbnail.webp \
  --alt "글 대표 이미지"

npx -y @roottale/cms-mcp cli entries create \
  --title "새 글" \
  --slug "new-post" \
  --body-file ./post.json \
  --featured-media-id "<업로드 응답의 id>"

npx -y @roottale/cms-mcp cli entries publish "<글 id>"
```

상위 `cli --help`는 `models`, `fields`, `entries`, `exposure-slots`,
`exposures`, `media` 그룹을 보여줍니다. 전체 하위 명령은
다음 도움말에서 확인하세요.

```bash
npx -y @roottale/cms-mcp cli entries --help
npx -y @roottale/cms-mcp cli models --help
npx -y @roottale/cms-mcp cli exposures --help
npx -y @roottale/cms-mcp cli media --help

# 특정 명령의 모든 옵션
npx -y @roottale/cms-mcp cli entries create --help
npx -y @roottale/cms-mcp cli media upload --help
```

항목 명령은 `list`, `get`, `create`, `update`, `publish`, `unpublish`,
`set-terms`, `delete`,
미디어 명령은 `list`, `upload`, `update`, `delete`를 제공합니다.

내부 운영 저장소에서는 같은 기능을 `rt cms entries ...`,
`rt cms media ...` 명령으로도 실행할 수 있습니다.

## 다음 단계

- 블로그 페이지 구현 → `blog.md`
- 발행 즉시 사이트 반영 → `revalidation-webhooks.md`
- 설정(디자인·메뉴·사업장 정보) 저장 즉시 반영 → `revalidation-webhooks.md` §1
  "설정 저장" + `theme-and-settings.md` (수신 라우트의 `revalidateTag` 주입과
  조회의 `tags` 를 **둘 다** 해야 합니다)
- HTTP 자동화 엔드포인트 → `api-reference.md`
