# API 키 및 개발자 액세스

Source: https://support.kapsulehost.com/ko-kr/developer-api-access

KapsuleHost는 두 가지 개발자 인터페이스를 제공합니다. 계정을 프로그래밍 방식으로 읽기 위한 범위가 지정된 API 키와 사용자 머신 및 CI 러너에서 Turborepo 및 Nx 빌드를 가속화하는 원격 빌드 캐시입니다.

둘 다 기본적으로 활성화되지 않습니다. 둘 다 **설정**에서 생성되며, 둘 다 비밀을 정확히 한 번 제공합니다.

## API 키 생성

API 키는 **설정**, **보안**, **API 키** 카드 아래에 있습니다.

![KPanel 보안 설정의 API 키 카드와 범위 칩이 표시되어 있습니다](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. **설정**으로 이동한 다음 **보안**을 선택합니다.
2. **API 키**로 스크롤한 후 **새 키**를 클릭합니다.
3. 키에 이름을 지정합니다. 필드에 "키 이름 (예: 내 자동화 스크립트)"라고 제안합니다. 이름은 사용자 참조용이므로 키가 사용될 위치를 명시하도록 작성합니다.
4. 범위 칩을 클릭하여 키가 수행할 수 있는 작업을 선택합니다. 3개의 읽기 범위가 미리 선택됩니다: `read:sites`, `read:email`, `read:domains`. 칩을 클릭하여 추가하거나 제거합니다.
5. **생성**을 클릭합니다.

전체 키는 "지금 복사"라는 제목의 녹색 패널에 한 번만 나타납니다. 이를 곧바로 비밀 저장소에 복사합니다. 해당 패널을 닫으면 키는 사라지고 짧은 접두사만 유지되며, 이것이 목록에서 다시 표시될 수 있는 전부입니다.

> **Warning:** 키는 두 번째로 표시되지 않으며 복구할 수 없습니다. 키를 잃어버렸다면 해당 키를 취소하고 새 키를 생성합니다. 공유 문서, 티켓, 커밋 또는 채팅 메시지에 붙여넣지 않습니다.

**소유자** 및 **관리자** 역할만 키를 생성할 수 있습니다. 다른 역할은 권한 오류를 받습니다. 키가 생성되면 보안 경고 이메일이 해당 키를 생성한 사람의 주소로 전송되므로 예상치 못한 경우 즉시 조사할 가치가 있습니다.

## 범위

7가지 범위가 제공됩니다:

| 범위 | 권한 |
|---|---|
| `read:sites` | 웹사이트 읽기 |
| `write:sites` | 웹사이트에 대한 쓰기 작업을 위해 예약됨 |
| `read:email` | 사서함 읽기 |
| `write:email` | 사서함에 대한 쓰기 작업을 위해 예약됨 |
| `read:domains` | 도메인 읽기 |
| `write:domains` | 도메인에 대한 쓰기 작업을 위해 예약됨 |
| `read:billing` | 청구 데이터 읽기를 위해 예약됨 |

> **Note:** 고객 API는 현재 읽기 전용입니다. `write:` 범위 및 `read:billing`은 키에서 선택할 수 있지만 현재 고객 엔드포인트가 사용하지 않으므로 이들을 부여해도 아무것도 변경되지 않습니다. 실제로 필요한 읽기 범위만 부여하고 쓰기 엔드포인트가 출시되면 키를 다시 확인합니다.

## 키 사용

`Authorization` 헤더에서 키를 베어러 토큰으로 보냅니다.

```sh
curl https://kpanel.kapsulehost.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

3개의 엔드포인트가 고객 API 키를 허용합니다:

| 엔드포인트 | 필요한 범위 | 반환 |
|---|---|---|
| `GET /api/v1/sites` | `read:sites` | 도메인, 애플리케이션 유형 및 상태가 포함된 웹사이트 |
| `GET /api/v1/domains` | `read:domains` | 상태 및 만료일이 포함된 도메인 |
| `GET /api/v1/mailboxes` | `read:email` | 사서함 |

키가 없거나 알 수 없거나 취소된 키를 사용한 요청은 `401`를 반환합니다. 올바른 범위가 없는 유효한 키는 필요한 범위를 명시하는 메시지와 함께 `403`을 반환합니다. 성공한 모든 호출은 키의 마지막 사용 타임스탬프를 업데이트합니다.

> **Tip:** 천천히 폴링합니다. 이러한 엔드포인트는 라이브 계정 데이터를 읽으며, 대량의 루프는 악용과 구별되지 않습니다. 대시보드가 필요로 하는 항목의 경우 1분에 한 번이 충분하고, 보통 1시간에 한 번이면 충분합니다.

## 키 검토 및 취소

API 키 테이블은 각 활성 키를 **이름**, **접두사** (키의 표시 시작) 및 **범위**로 나열합니다. 행 끝의 **취소**를 클릭하여 비활성화합니다.

> **Important:** 취소는 즉시 적용되며 확인 대화가 없습니다. 해당 키를 사용한 다음 요청은 `401`을 사용하여 실패합니다. 취소된 키는 복구할 수 없으므로 클릭하기 전에 이를 사용하는 항목을 파악해야 합니다.

키는 이를 생성한 사람이 아니라 **계정**에 속합니다. [팀 페이지](https://support.kapsulehost.com/ko-kr/account-team-members)에서 팀원을 제거해도 해당 팀원이 생성한 키는 취소되지 않습니다. 오프보딩에 키 검토를 포함시킵니다. 사람을 제거한 다음 여기로 돌아와 그들이 생성한 항목을 모두 취소합니다.

키 생성 및 취소는 모두 [감사 로그](https://support.kapsulehost.com/ko-kr/account-audit-log)에서 `api_key.*` 작업 아래 행위자 및 원래 IP 주소와 함께 기록됩니다.

## 원격 빌드 캐시

설정 레일의 고급 그룹에 있는 **개발자** 페이지는 **원격 빌드 캐시**를 제공합니다. 패널은 이를 "Turborepo 및 Nx 빌드를 가속화하여 머신 및 CI 파이프라인 전체에서 분산 캐시를 공유하는 방법"으로 설명합니다.

1. **설정**으로 이동한 다음 **개발자**를 선택합니다.
2. **원격 캐시 활성화**를 클릭합니다.
3. "새 토큰이 생성되었습니다. 지금 복사하세요. 다시는 표시되지 않습니다"라는 제목의 패널에서 토큰을 복사합니다.

그런 다음 CI 구성 또는 로컬 `.env.local`에서 두 가지 환경 변수를 설정합니다:

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

팀 ID는 동일한 페이지의 설정 지침에 표시된 KapsuleHost 계정 ID입니다.

이 페이지는 자신의 호환성을 명시합니다: Turborepo 1.x 이상, Nx 16 이상, 동일한 원격 캐시 프로토콜을 구현하는 모든 도구입니다. 아티팩트는 계정별로 저장되며 절대 계정 전체에서 공유되지 않습니다.

카드에는 두 가지 추가 컨트롤이 있습니다:

- **토큰 회전**은 새 토큰을 발급하고 이전 토큰을 무효화합니다. 이전 토큰을 보유한 모든 CI 작업이 캐시 사용을 중지하므로 토큰을 회전하고 비밀을 함께 업데이트합니다.
- **비활성화**는 캐시를 완전히 끕니다.

## 둘 중 하나 선택

이들은 서로 관련 없는 문제를 해결하며 서로 교환할 수 없습니다.

KapsuleHost 외부의 항목이 계정 상태를 알아야 할 때 **API 키**를 사용합니다. 사이트를 나열하는 상태 보드, 도메인 만료가 임박했다는 경고를 표시하는 스크립트, 인벤토리 내보내기입니다.

모든 머신 및 모든 CI 실행이 동일한 변경되지 않은 패키지를 다시 빌드하기 때문에 빌드가 느릴 때 **원격 빌드 캐시**를 사용합니다. 호스팅된 사이트와 관련이 없으며 계정 데이터를 읽지 않습니다.

## 문제 해결

**모든 요청이 401을 반환합니다.** 헤더를 `Authorization: Bearer <key>`로 단일 공백으로 보냈는지, 키를 복사할 때 잘리지 않았는지, 취소되지 않았는지 확인합니다. 키의 시작 부분을 **접두사** 열과 비교하여 사용 중인 키가 맞는지 확인합니다.

**요청이 범위를 명시하는 403을 반환합니다.** 키에 해당 범위가 없습니다. 범위는 키가 생성될 때 고정되므로 올바른 범위를 사용하여 대체 키를 생성하고 이전 키를 취소합니다.

**API 키 카드를 볼 수 없습니다.** 개발자 페이지가 아니라 보안 페이지에 있습니다. 개발자 페이지는 빌드 캐시만 보유합니다.

**새 키 버튼이 아무것도 하지 않습니다.** 역할이 관리자 이하입니다. 소유자 또는 관리자에게 문의합니다.

**빌드가 캐시에 도달하지 않습니다.** `TURBO_TOKEN` 및 `TURBO_TEAM`이 모두 빌드 환경에 있는지, 토큰을 설정한 이후로 회전하지 않았는지, 페이지에 여전히 **활성** 배지가 표시되는지 확인합니다.

**내가 생성하지 않은 키가 나타났습니다.** 이를 손상으로 취급합니다. 취소한 다음 [계정 보안](https://support.kapsulehost.com/ko-kr/account-security)을 확인하고 [감사 로그](https://support.kapsulehost.com/ko-kr/account-audit-log)에서 변경된 다른 항목을 확인합니다.