API 인증과 접근 권한 이해하기
HTTP API, CLI, MCP가 사용하는 OAuth 인증과 사이트별 권한, 플랜 조건을 구분해 알아봅니다.
Neopress는 https://app.neopress.ai/api/v1 아래에 HTTP API를 제공합니다. CLI와 MCP는 이 API로 사이트 리소스를 관리합니다. Neopress 도구가 사용하는 자동화 인터페이스이며, OAuth 인증과 사이트별 접근 권한을 적용합니다.
새로운 연동을 시작할 때는 공개된 CLI 또는 MCP 패키지를 사용하세요. 외부 서비스용 API 키를 발급하는 공개 절차는 제공하지 않습니다. CLI와 MCP 안에서 사용하는 SDK도 내부에 포함되어 있으며, 별도로 설치하는 공개 패키지가 아닙니다.
인증은 어떻게 이루어지나요?
CLI는 브라우저 로그인 후 갱신 가능한 세션을 로컬에 저장합니다. 원격 MCP는 AI 도구에서 OAuth 연결을 시작하고, 사용자가 로그인과 접근 승인을 진행합니다. 인증된 HTTP 요청에는 Authorization 헤더로 OAuth 액세스 토큰을 전달합니다.
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN액세스 토큰은 로그인한 계정을 나타내며 영구 API 키가 아닙니다. CLI는 NEOPRESS_ACCESS_TOKEN 환경 변수로도 유효한 OAuth 토큰을 받을 수 있습니다. 환경 변수의 토큰은 저장된 세션보다 우선하므로, 토큰을 제공하는 환경에서 유효 기간과 갱신을 관리해야 합니다.
액세스 토큰을 페이지 TSX, 공개 브라우저 코드, 저장소 파일, 공개 예제에 넣지 마세요. Neopress 페이지는 관리 API에 직접 로그인하는 대신, 페이지 런타임이 전달하는 데이터와 폼 클라이언트를 사용합니다.
접근 가능 여부를 결정하는 세 가지 조건
계정과 사이트 참여: 세션이 유효하고 로그인한 계정이 대상 사이트에 접근할 수 있어야 합니다.
사이트 작업 권한: 페이지와 레이아웃 수정에는 사이트 제작 권한, CMS 콘텐츠 수정에는 콘텐츠 권한, 분석 조회에는 분석 권한이 필요합니다. 발행 권한도 별도로 확인하며, API를 통한 사이트 발행에는 추가로 소유자 또는 관리자 역할이 필요합니다.
사이트 플랜: 개발자 도구는 Launch부터 사용할 수 있습니다. Growth에도 포함되며 유효한 체험 기간에는 Launch 권한이 적용됩니다. 활성 이용 권한이 없는 Archive 사이트에서는 일반 사이트 조회를 포함해 이 인터페이스를 사용할 수 없습니다.
상위 플랜을 사용해도 계정에 없는 팀 권한이 추가되지는 않습니다. 기능별 조건도 유지됩니다. 사이트 언어를 추가하거나 저장된 분석 이벤트와 퍼널 기능을 사용하려면 Growth 권한이 필요합니다.
OAuth 스코프와 사이트 권한 구분하기
MCP 클라이언트가 제공하는 OAuth 절차를 그대로 사용하세요. 연결 설정에 pages:write 같은 사용자 정의 스코프를 임의로 추가하지 마세요. Neopress는 요청마다 계정의 현재 사이트 권한을 확인합니다. INSUFFICIENT_SCOPE 응답은 해당 역할이나 작업 권한으로 요청을 수행할 수 없다는 뜻입니다. 더 강한 API 키를 발급해야 한다는 의미가 아닙니다.
HTTP 요청과 응답 살펴보기
아래는 이미 유효한 OAuth 액세스 토큰을 제공하는 환경에서 사용할 수 있는 조회 요청 예시입니다. 사이트 ID는 본인의 사이트 ID로 바꾸세요.
curl 'https://app.neopress.ai/api/v1/sites/123/pages' --header "Authorization: Bearer $NEOPRESS_ACCESS_TOKEN"API의 성공 응답에는 data가 있으며 페이지 단위로 조회하는 목록에는 pagination이 함께 들어갑니다. 오류 응답에는 코드, 메시지, 상태를 담은 error 객체가 있습니다. CLI는 사용하기 편하도록 응답의 일부를 꺼내 보여주기도 하므로 HTTP 원본과 출력 모양이 항상 같지는 않습니다.
요청 제한은 작업마다 다릅니다. 응답에 X-RateLimit-Limit와 X-RateLimit-Remaining이 있으면 확인하고, 429 RATE_LIMITED 응답을 받으면 요청 간격을 늘리세요. 자동화에서도 초안 저장, 컴파일 성공, 발행 성공을 서로 다른 결과로 다뤄야 합니다.