/api/preview/*로 가는 모든 요청은 bearer API 키로 인증됩니다.
키 발급하기
대시보드의 Settings → Developers로 이동하세요. 키 이름을 지정하고(로테이션 시 여러 키를 구분하기 위해), 범위를 선택한 뒤 발급합니다. 전체 키 값은 딱 한 번만 표시됩니다. DocuRise는 평문 시크릿을 저장하거나 다시 보여주지 않습니다 — 이후에는 키 id 앞부분(예:dr_live_ab12****)과 범위, 생성일, 마지막 사용일만 표시됩니다.
여러 키를 동시에 활성 상태로 둘 수 있습니다 — 다운타임 없이 로테이션하려면 기존 키를 폐기하기 전에 새 키를 먼저 발급하세요.
범위(Scope)
읽기 범위(
documents:read, analytics:read, email:read, automations:read, products:read,
instagram:read)는 조회만 가능합니다. 키를 발급할 때 읽기 전용 버튼을 누르면 정확히 이
범위들만 선택됩니다. 여기에 나열된 범위가 아직 출시되지 않은 엔드포인트용일 수도 있습니다.
범위 자체는 이미 존재하므로 미리 부여해 둘 수 있습니다.
호출하는 라우트에 필요한 범위가 키에 없으면 403 INSUFFICIENT_SCOPE 에러가 반환됩니다. 모든 에러 코드와 대응 방법은 에러를 참고하세요.
기존 키에 범위 추가하기
키는 생성 당시의 범위를 그대로 유지하므로, 이후 릴리스에서 추가된 범위는 기존 키에 없습니다. 릴리스 이후 호출이403 INSUFFICIENT_SCOPE를 반환하기 시작했다면, Settings → Developers에서
해당 키의 권한 수정을 선택하고 필요한 범위를 체크하세요. 키 자체는 바뀌지 않으므로 비밀 값을
교체할 필요가 없습니다. 폐기된 키는 수정할 수 없습니다.
GET /api/preview/whoami를 호출하면 키가 현재 가진 범위를 확인할 수 있습니다.
요금제 조건
범위와 별개로, 모든 라우트는 API가 포함된 요금제여야 합니다. 범위가 맞아도 API가 포함되지 않은 요금제이면403 PLAN_REQUIRED 에러가 반환됩니다.
키 폐기하기
같은 Settings → Developers 페이지에서 키를 폐기할 수 있습니다. 폐기는 즉시 적용되며 되돌릴 수 없습니다 — 폐기 직후 해당 키로 보낸 요청은 바로 인증에 실패합니다 (401 UNAUTHORIZED). 폐기된 키는 목록에는 남아 있지만 다시 활성화할 수 없습니다 — 필요하면 새 키를 발급하세요.
프리뷰 접근 조건
API는 일부 계정에서만 사용이 가능합니다. 요금제·범위와 별개로 API를 사용할 수 있는 계정에서만 키가 동작하며, 그렇지 않은 계정은 모든 라우트에서404를 받습니다 사용할 수 있어야 하는 계정인데 404가 나온다면 DocuRise 담당자에게 문의하세요. 접근 권한이 있는 계정이라도 플랜에 API가 포함되어 있지 않으면 404가 아니라 403 PLAN_REQUIRED로 응답합니다.