시작하기
인증
각 Kanorio API가 허용하는 자격 증명, 권한 계산 방법, 토큰을 안전하게 회전하고 해지하는 방법을 설명합니다.
각 Kanorio API는 서로 다른 호출자를 위해 구축되었으며, 각각 고유한 자격 증명을 허용합니다. 호출자가 누구를 대신하여 동작하는지 확인하고 적절한 자격 증명을 선택하십시오.
| 자격 증명 | 접두사 | 권한 주체 | 허용 API | 용도 |
|---|---|---|---|---|
| 개인 액세스 토큰 | knr_pat_ | 본인 (선택한 사이트 및 권한으로 제한) | Management API, MCP | 스크립트, CLI, 키를 사용하는 코딩 어시스턴트 |
| 서비스 계정 토큰 | knr_sa_ | 사이트 자체 (개인이 아님) | Management API, MCP | CI, 스케줄러, 사용자가 떠나도 계속 실행되어야 하는 파트너 백엔드 |
| OAuth 액세스 토큰 | knr_at_ | 본인 (승인한 앱을 통해) | MCP 전용 | Claude나 ChatGPT와 같이 커넥터가 내장된 어시스턴트 |
| 미리보기 토큰 | knr_pv_ | 특정 사이트의 초안에 대한 읽기 전용 액세스 | Content Delivery API | 프론트엔드의 초안 모드 |
| 고객 토큰 | knr_cat_ | 특정 사이트에 로그인한 고객 1명 | Customer API, 제한된 Content Delivery API 읽기 | 프론트엔드에서의 로그인, 구매 콘텐츠 및 주문 |
Content Delivery API는 게시된 콘텐츠에 대해 자격 증명이 필요하지 않습니다.
Management API
https://app.kanorio.com/api/v1로 보내는 모든 요청에 토큰을 Bearer 자격 증명으로 포함하여 보내십시오.
curl https://app.kanorio.com/api/v1/sites \ -H "Authorization: Bearer knr_pat_..."
개인 액세스 토큰
계정 설정 › API 액세스에서 생성합니다. 생성 시 다음을 선택합니다.
- 사이트: 특정 사이트 또는 나중에 생성할 사이트를 포함한 모든 사이트. 새 사이트를 생성하려면 모든 사이트에 대한 권한이 필요합니다.
- 권한: 프리셋(읽기 전용, 콘텐츠 편집, 전체 액세스) 또는 개별 권한.
- 만료: 토큰은 항상 만료됩니다. 만료 전에 이메일과 받은 편지함 알림을 받게 됩니다.
사이트에서 토큰의 유효 권한은 토큰이 허용하는 범위와 해당 사이트에서 사용자의 역할이 허용하는 범위의 교집합입니다. 전체 액세스 권한 토큰이라도 사용자가 뷰어인 사이트는 편집할 수 없으며, 사이트 소유자만 게시를 취소할 수 있습니다.
어떤 프리셋을 선택하든 토큰에 절대 부여되지 않는 권한이 있습니다. 여기에는 뉴스레터 전송 또는 예약, 데이터 내보내기, 환불, 연락처 삭제, 멤버 또는 결제 관리가 포함됩니다. 에이전트는 뉴스레터 초안을 작성할 수 있지만, 전송은 관리 화면에서 사람이 직접 수행해야 합니다.
서비스 계정
서비스 계정은 개인이 아닌 사이트에 속합니다. 생성자가 팀을 떠나도 계속 작동하며, 서비스 계정을 해지하면 해당 계정이 발행한 모든 토큰이 즉시 무효화됩니다.
- 사이트 설정 › 개발자를 열고 서비스 계정을 추가합니다. 본인이 가진 권한만 부여할 수 있습니다.
- 서비스 계정을 열고 토큰을 발행합니다. "GitHub Actions"와 같이 사용될 곳에 맞춰 이름을 지정하십시오.
knr_sa_값은 한 번만 표시됩니다.
서비스 계정은 해당 사이트 내에서만 작동합니다. 사이트 생성이나 모든 사이트 목록 조회와 같은 계정 수준의 작업은 403 FORBIDDEN을 반환합니다. OpenAPI 문서의 각 작업은 x-kanorio-principals에 허용되는 호출자를 나열합니다. SERVICE_ACCOUNT가 포함된 작업은 서비스 계정 토큰을 허용합니다.
서비스 계정의 권한을 좁히면 기존 토큰에도 즉시 반영됩니다. 권한을 넓히는 것은 이후 발행된 토큰에만 적용됩니다.
스코프
Management API 참조의 각 작업은 필요한 권한을 보여줍니다. OpenAPI 문서에는 x-kanorio-required-scope로 동일한 값이 포함되어 있습니다. 권한이 없는 토큰은 403 FORBIDDEN을 받습니다. 현재 토큰으로 무엇을 할 수 있는지 확인하려면 GET /whoami를 호출하십시오.
MCP
https://app.kanorio.com/api/mcp의 MCP 서버는 개인 액세스 토큰 및 서비스 계정 토큰과 OAuth 2.1 액세스 토큰을 허용합니다. 내장 커넥터가 있는 어시스턴트는 인증 서버를 자동으로 검색하고 브라우저에서 액세스 승인을 요청합니다. OAuth 액세스 토큰은 MCP 서버에 바인딩되어 있으며 REST 엔드포인트에서는 거부됩니다. MCP를 참조하십시오.
Content Delivery API
게시된 콘텐츠는 공개되어 있으며 엣지 캐시되므로 브라우저에서 직접 호출할 수 있습니다.
- 다른 오리진에서의 브라우저 호출은 사이트 설정 › 개발자의 허용된 오리진에 해당 오리진이 있어야 합니다.
localhost및 모든 포트의127.0.0.1은 항상 허용됩니다. CORS는 브라우저가 읽을 수 있는 내용을 제어합니다. 이는 인증 경계가 아니며, 미리보기 토큰 없이는 초안이 제공되지 않습니다. - 초안 미리보기: 동일한 설정 페이지 또는
POST /sites/{id}/preview-tokens를 사용하여knr_pv_미리보기 토큰을 생성합니다. 서버에서X-Kanorio-Preview: knr_pv_...로 전송하십시오. 미리보기 응답은 캐시를 우회하며 저장되지 않습니다.
Customer API
고객은 비밀번호 없이 로그인합니다. 사이트 소유자는 사이트 설정 › 고객 계정에서 사용할 방법을 선택합니다. 사이트 문서의 customerAccess.methods는 활성화된 방법을 표시 순서대로 나열합니다. 모든 방법은 동일한 knr_cat_ 세션 토큰으로 종료됩니다.
- 이메일 코드(
email_code, 항상 켜짐) 및 매직 링크(email_link): 이메일 주소로POST /api/v1/customer/auth/challenge를 호출하면 코드가 전송됩니다. 먼저GET /api/v1/customer/auth/protection에서 봇 체크를 가져옵니다. 내장 체크(provider: "kanorio")인 경우@kanorio/sdk의solveProtectionChallenge로 해결하고 필드를 요청에 포함합니다. 소유자의 Turnstile, reCAPTCHA 또는 hCaptcha 키를 사용하는 경우siteKey와action으로 위젯을 렌더링하고 해당 토큰을captchaToken으로 전송합니다. 그런 다음{ "method": "code", "email", "code" }또는{ "method": "link", "token" }을 사용하여POST /api/v1/customer/auth/verify를 호출합니다. - Google(
google):{ "method": "google", "baseUrl": <페이지의 오리진> }과 함께POST /api/v1/customer/auth/oauth/start를 호출하면 공급자 URL이 반환되므로 브라우저를 해당 URL로 리디렉션합니다. Kanorio는 동의 화면을 호스팅하고?handoff=를 붙여 브라우저를baseUrl로 다시 보냅니다. 60초 이내에{ "method": "handoff", "token" }을 사용하여POST /api/v1/customer/auth/verify로 교환하십시오. Google 계정 이메일이 확인되지 않은 경우, 고객은 대신 이메일 코드를 받게 되며?email=&verify=1이 붙은 상태로 페이지에 도착합니다. - 패스키(
passkey):POST /api/v1/customer/auth/passkey/options를 호출하고 옵션으로navigator.credentials.get()을 실행한 다음, 어설션과challengeId를 사용하여POST /api/v1/customer/auth/passkey/verify를 호출합니다. 로그인한 고객은/api/v1/customer/passkeys에서 패스키를 관리합니다. 패스키는 사이트의 기본 도메인에 바인딩되므로 인증 과정은 해당 오리진에서 실행되어야 합니다.
로그인 UI에서 POST /api/v1/customer/auth/challenge의 응답을 처리하십시오.
| 코드 | 대처 방법 |
|---|---|
429 RATE_LIMITED | retryAfter초 동안 대기한 후 고객에게 다시 시도하도록 안내하세요 |
403 BOT_PROTECTION_FAILED | 새로운 챌린지를 가져오거나(또는 위젯을 재설정) 다시 전송하세요 |
503 SERVICE_UNAVAILABLE | 로그인 기능을 일시적으로 사용할 수 없습니다. 재시도 버튼을 표시하세요 |
503 SHARED_SENDER_PAUSED | 현재 이 사이트에서 이메일 로그인이 일시 중지되었습니다. 패스키나 Google 로그인을 제안하거나 고객에게 나중에 다시 시도하도록 안내하세요 |
200 응답은 이메일이 전송되었는지 여부를 밝히지 않습니다. Kanorio는 사이트의 로그인 볼륨에 따라 봇 체크를 조정합니다. /auth/protection의 챌린지는 표시 가능한 위젯(visible: true)이나 더 어려운 내장 퍼즐을 요구할 수 있으므로, 보이지 않는 흐름을 가정하지 말고 항상 가져온 챌린지를 기반으로 렌더링하십시오.
Customer API 호출 및 제한된 Content Delivery API 읽기 시 토큰을 Authorization: Bearer knr_cat_...으로 전송하십시오.
고객 토큰은 해당 사이트의 해당 고객만을 나타냅니다. 다른 사람의 데이터를 읽거나 Management API를 호출할 수 없습니다. <kanorio-login> 요소가 이 흐름을 자동으로 처리합니다.
토큰 회전 및 해지
- 회전: 개인 액세스 토큰 메뉴에서 회전합니다. Kanorio는 동일한 설정으로 새 토큰을 발행하며, 이전 토큰은 선택한 유예 기간(없음, 1시간, 1일) 동안 계속 작동합니다. 유출이 의심되면 '없음'을 선택하십시오.
- 해지: 토큰을 해지하면 즉시 사용이 중단됩니다. 해당 토큰을 사용한 다음 요청은
401 UNAUTHORIZED를 받습니다. 이미 완료된 작업은 롤백되지 않습니다. - 토큰으로 수행된 활동은 사이트 활동 로그에 해당 토큰 소유자 또는 서비스 계정의 이름으로 기록됩니다.
토큰 안전하게 관리하기
- 토큰은 환경 변수나 서버의 비밀 관리자에 저장하십시오.
NEXT_PUBLIC_접두사를 붙이거나 모바일 앱에 포함하지 마십시오. - 토큰을 AI 채팅에 붙여넣지 마십시오. 실제 도구는 구성 파일에서 읽어옵니다.
- 도구당 하나의 토큰, 통합당 하나의 서비스 계정을 사용하여 개별적으로 해지할 수 있도록 하십시오.
- 각 토큰에는 작동에 필요한 최소한의 사이트와 권한만 부여하십시오.