> ## Documentation Index
> Fetch the complete documentation index at: https://docurise.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증

> API 키, 범위(scope), 요청 인가 방식

`/api/preview/*`로 가는 모든 요청은 bearer API 키로 인증됩니다.

```
Authorization: Bearer dr_live_<keyId>_<secret>
```

## 키 발급하기

대시보드의 **Settings → Developers**로 이동하세요. 키 이름을 지정하고(로테이션 시 여러 키를 구분하기 위해), 범위를 선택한 뒤 발급합니다. 전체 키 값은 딱 한 번만 표시됩니다. DocuRise는 평문 시크릿을 저장하거나 다시 보여주지 않습니다 — 이후에는 키 id 앞부분(예: `dr_live_ab12****`)과 범위, 생성일, 마지막 사용일만 표시됩니다.

여러 키를 동시에 활성 상태로 둘 수 있습니다 — 다운타임 없이 로테이션하려면 기존 키를 폐기하기 전에 새 키를 먼저 발급하세요.

## 범위(Scope)

| 범위 | 권한 |
| - | - |
| `documents:write` | 문서 생성과 수정 (`POST /api/preview/documents`, `PATCH /api/preview/documents/{id}`) |
| `documents:read` | 문서(상태, 만료일, 이메일 보호 설정), 폴더, 코스 조회 |
| `analytics:read` | 문서 애널리틱스 조회 (조회수, 고유 방문자, 리드, 전환율) |
| `email:read` | 이메일 1회성 발송 및 이메일 집계 인사이트 조회 |
| `automations:read` | 자동화, 태그, 그룹 조회 (이름과 개수만) |
| `products:read` | 상품 목록 조회 |
| `contacts:tag` | 태그 만들기, 연락처 1명에 수동 태그 추가 또는 제거 |
| `segments:write` | 그룹 생성 |
| `instagram:write` | Instagram DM 규칙 생성·수정·일시정지·재개 (`POST`, `PATCH /api/preview/instagram/rules…`) |
| `instagram:read` | Instagram DM 규칙 목록·조회 (`GET /api/preview/instagram/rules…`) |

읽기 범위(`documents:read`, `analytics:read`, `email:read`, `automations:read`, `products:read`,
`instagram:read`)는 조회만 가능합니다. 키를 발급할 때 **읽기 전용** 버튼을 누르면 정확히 이
범위들만 선택됩니다. 여기에 나열된 범위가 아직 출시되지 않은 엔드포인트용일 수도 있습니다.
범위 자체는 이미 존재하므로 미리 부여해 둘 수 있습니다.

호출하는 라우트에 필요한 범위가 키에 없으면 `403 INSUFFICIENT_SCOPE` 에러가 반환됩니다. 모든 에러 코드와 대응 방법은 [에러](https://docurise.io/docs/ko/errors.md)를 참고하세요.

### 기존 키에 범위 추가하기

키는 생성 당시의 범위를 그대로 유지하므로, 이후 릴리스에서 추가된 범위는 기존 키에 없습니다.
릴리스 이후 호출이 `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`로 응답합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.