시작하기

API 키 발급, 환경변수 설정, 패키지 설치, 첫 콘텐츠 조회

1. API 키 발급

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

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

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

2. 환경변수

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

3. 패키지 설치

# 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 사용 시).

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

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

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

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

4. 첫 조회 — 동작 확인

// 서버 컴포넌트, 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로 글과 이미지 자동화

MCP 설정의 ROOTTALE_API_KEY에 read_write 키를 넣으면 다음 tool을 쓸 수 있습니다.

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

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

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

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

6. CLI로 자동화

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

export ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx

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

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

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

상위 cli --help는 posts, media 그룹만 보여줍니다. 전체 하위 명령은 다음 도움말에서 확인하세요.

npx -y @roottale/cms-mcp cli posts --help
npx -y @roottale/cms-mcp cli media --help

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

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

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

다음 단계

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

제품

업종별 제작

제품