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

# API 키

> CaseBender API 키를 생성하고 범위를 지정하며 모니터링, 교체, 일시 중지, 해지하고 안전하게 사용합니다.

## 개요

API 키는 CaseBender에 대한 프로그래밍 방식의 액세스를 제공합니다. 사용자 계정 및 현재 조직에서 사용할 수 있는 키를 관리하려면 **설정 → 계정 → API 키**를 엽니다.

페이지에서는 다음 기능을 제공합니다.

* 검색 및 상태 또는 티어 필터
* 마스킹된 키 식별자
* 상태, 티어, 마지막 사용 시간 및 요청 수
* 사용 통계
* 교체, 일시 중지, 해지 및 삭제와 같은 수명 주기 작업

<Warning>
  API 키는 자격 증명입니다. 승인된 보안 비밀 관리자에 보관하고, 소스 제어에 커밋하거나 로그, 스크린샷, 티켓 또는 채팅 메시지에 포함하지 마세요.
</Warning>

## 사전 요구 사항

* 역할에서 쓰기 작업 및 API 키 관리를 허용해야 합니다.
* 사용 가능한 범위는 역할에 따라 필터링됩니다.
* 키를 생성, 해지 또는 삭제할 때 추가 인증이 필요할 수 있습니다.
* 조직에서 추가 인증 및 액세스 정책을 적용할 수 있습니다.

읽기 전용 역할은 허용된 정보를 볼 수 있지만 키를 변경할 수 없습니다.

## API 키 생성

<Steps>
  <Step title="API 키 열기">
    **설정 → 계정 → API 키**로 이동합니다.
  </Step>

  <Step title="생성 시작">
    **API 키 생성**을 선택합니다.
  </Step>

  <Step title="키 설명">
    워크로드, 소유자 및 용도를 식별할 수 있는 명확한 **이름**과 선택 사항인 설명을 입력합니다.
  </Step>

  <Step title="티어 선택">
    워크로드의 예상 요청량에 적합한 티어를 선택합니다. 사용 가능한 티어는 **Basic**부터 **Unlimited**까지입니다.
  </Step>

  <Step title="만료 설정">
    선택적으로 만료까지 남은 일수를 입력합니다. 프로덕션 자격 증명에는 정책에 부합하는 짧은 유효 기간을 권장합니다.
  </Step>

  <Step title="범위 선택">
    범위를 하나 이상 선택합니다. 워크로드에 역할에서 사용할 수 있는 모든 범위가 실제로 필요한 경우에만 **모두 선택**을 사용하세요.
  </Step>

  <Step title="생성 및 인증">
    **키 생성**을 선택하고 메시지가 표시되면 추가 인증을 완료합니다.
  </Step>

  <Step title="자격 증명 저장">
    **API 키 저장**에 표시된 전체 키를 승인된 보안 비밀 관리자에 복사한 다음 **완료**를 선택합니다.
  </Step>
</Steps>

<Warning>
  전체 키는 한 번만 표시됩니다. CaseBender는 키 검증 및 식별에 필요한 정보만 저장하므로 일반 텍스트 자격 증명은 나중에 다시 가져올 수 없습니다.
</Warning>

## 범위 선택

범위는 `cases:read` 또는 `organizations:*`와 같은 리소스-작업 패턴을 사용합니다. 범위 범주에는 케이스, 보안 경보, 작업, 사용자, 팀, 조직, 설정 및 API 키 관리가 포함될 수 있습니다.

최소 권한 원칙을 따르세요.

* 보고 및 검색 워크로드에는 읽기 전용 범위를 사용하세요.
* 통합에서 변경 작업을 수행하는 경우에만 쓰기 범위를 부여하세요.
* 단일 용도 통합에는 와일드카드 및 관리 범위를 사용하지 마세요.
* 서로 관련 없는 서비스 또는 환경에는 별도의 키를 생성하세요.
* 통합이 변경될 때마다 필요한 범위를 검토하세요.

설정의 생성 양식에는 현재 역할에서 허용하는 범위만 표시됩니다. API 요청은 키의 범위와 적용되는 기타 데이터 제어에 따라 평가됩니다.

<Warning>
  `api-keys:write`, 와일드카드 또는 관리 범위는 다른 자격 증명을 생성하거나 관리하도록 명시적으로 승인된 신뢰할 수 있는 자동화에만 부여하세요.
</Warning>

## 티어 선택

티어에는 키에 의도된 서비스 등급이 기록됩니다. 사용 가능한 티어는 다음과 같습니다.

* **Basic**
* **Standard**
* **Professional**
* **Enterprise**
* **Unlimited**

실제 요청, 대량 작업 및 동시 실행 제한은 배포 구성에 따라 달라집니다. 티어를 선택하면 활성 제한이 변경되거나 키가 무제한으로 바뀐다고 가정하지 말고, 플랫폼 관리자와 함께 프로덕션 처리량 및 적용 방식을 검증하세요.

## API 요청 인증

지원되는 단일 키 헤더 중 하나에 전체 키를 사용합니다.

### 권장: Bearer 토큰

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "Authorization: Bearer $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

### 대안: X-Api-Key

```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
  --header "X-Api-Key: $CASEBENDER_API_KEY" \
  --header "Content-Type: application/json"
```

<Note>
  키를 환경 변수 또는 보안 비밀 주입 메커니즘에 저장하세요. 실제 키를 셸 기록이나 소스 코드에 직접 붙여 넣지 마세요.
</Note>

추가 예제는 [API 레퍼런스 소개](/ko/api-reference/introduction)를 참조하세요.

## 키 상태 이해

* **활성** 키는 범위 및 정책 검사를 통과하면 요청을 인증할 수 있습니다.
* **일시 중지됨** 키는 일시적으로 비활성화되며 다시 활성화할 수 있습니다.
* **해지됨** 키는 영구적으로 유효하지 않습니다.
* **만료됨** 키는 구성된 만료 시점이 지났습니다.

## 사용 통계 보기

키의 작업 메뉴를 열고 **통계 보기**를 선택하여 다음을 검토합니다.

* 총 요청 수
* 성공한 요청 수
* 실패한 요청 수
* 평균 응답 시간
* 상위 엔드포인트

이러한 통계를 사용하여 사용되지 않는 자격 증명, 예상하지 못한 엔드포인트 및 다른 티어가 필요한 워크로드를 식별하세요.

## 키 교체

교체하면 현재 보안 비밀이 새 보안 비밀로 대체됩니다.

<Steps>
  <Step title="사용 서비스 준비">
    키를 사용하는 서비스를 즉시 업데이트할 수 있고 롤백 계획이 있는지 확인합니다.
  </Step>

  <Step title="교체">
    키의 작업 메뉴를 열고 **키 교체**를 선택합니다.
  </Step>

  <Step title="새 키 저장">
    새로 표시된 자격 증명을 보안 비밀 관리자에 복사합니다.
  </Step>

  <Step title="업데이트 및 검증">
    키를 사용하는 워크로드를 업데이트하고 필요에 따라 다시 시작하거나 재배포한 다음 범위가 지정된 테스트 요청을 실행합니다.
  </Step>
</Steps>

<Warning>
  교체하면 이전 보안 비밀이 무효화됩니다. 통합 중단을 방지하도록 변경 작업을 조율하세요.
</Warning>

교체는 운영자가 시작합니다. 교체 간격이 저장되어 있다고 해서 CaseBender가 대체 키를 자동으로 교체하고 배포하는 것은 아닙니다.

## 키 일시 중지 또는 재활성화

조사 또는 계획된 유지 관리 중에 키 사용을 일시적으로 중지하려면 **일시 중지**를 사용합니다. 자격 증명과 해당 사용 서비스가 신뢰할 수 있음을 확인한 후에만 **재활성화**를 사용하세요.

되돌릴 수 있는 차단 조치가 필요한 경우 삭제보다 일시 중지를 권장합니다.

## 키 해지

자격 증명이 침해되었거나 더 이상 신뢰할 수 없거나 영구적으로 사용을 종료할 때 **해지**를 사용합니다. 해지에는 추가 인증이 필요할 수 있으며 되돌릴 수 없습니다.

해지 후 다음을 수행하세요.

1. 모든 사용 서비스에서 보안 비밀을 제거합니다.
2. 사용 통계와 보안 원격 측정 데이터를 검토합니다.
3. 예상하지 못한 요청을 조사합니다.
4. 워크로드가 계속 승인된 경우에만 별도의 대체 키를 생성합니다.

## 키 삭제

삭제하면 키 레코드와 직접 관리할 수 있는 기능이 제거됩니다. 추가 인증이 필요할 수 있습니다.

<Warning>
  자격 증명 사용 종료 절차를 명확하게 남겨야 하는 경우 키를 삭제하기 전에 해지하세요. 현재 작업 메뉴는 모든 파괴적 작업에 별도의 확인 대화 상자를 제공하지 않습니다.
</Warning>

## 보안 권장 사항

* 실명으로 식별되는 담당자와 워크로드 소유자를 지정하세요.
* 프로덕션, 스테이징 및 개발 환경에 별도의 키를 사용하세요.
* 자격 증명 정책에 맞는 만료 시간을 설정하세요.
* 노출이 의심되면 즉시 교체하세요.
* 실패한 요청과 예상하지 못한 엔드포인트를 모니터링하세요.
* 사용하지 않는 키를 활성 상태로 두지 말고 해지하세요.
* 이메일 또는 협업 도구를 통해 키를 전송하지 마세요.

## 문제 해결

### 키 생성이 거부됨

이름을 입력하고 범위를 하나 이상 선택한 다음, 역할에 쓰기 액세스 권한이 있는지 확인하고 필요한 추가 인증 절차를 완료하세요.

### API 요청에서 401을 반환함

활성 상태인 전체 키가 Bearer 토큰 또는 `X-Api-Key`로 제공되었는지 확인하고, 키가 만료, 일시 중지 또는 해지되지 않았는지 확인하세요.

### API 요청에서 403을 반환함

키 인증에는 성공했지만 필요한 범위 또는 데이터 액세스 권한이 없습니다. 승인된 키 관리 워크플로우를 통해 필요한 최소 범위만 추가하세요.

### 요청이 속도 제한됨

요청 빈도를 줄이고 응답의 재시도 지침을 따르거나 워크로드에 다른 티어가 필요한지 관리자에게 문의하세요.

### 전체 키가 더 이상 표시되지 않음

일반 텍스트 키는 다시 가져올 수 없습니다. 키를 교체하거나 대체 키를 생성한 후 사용 서비스를 업데이트하세요.

## API 레퍼런스

* [API 키 목록 조회](/en/api-reference/endpoint/api-keys/list)
* [API 키 생성](/en/api-reference/endpoint/api-keys/create)
* [사용 가능한 범위 목록 조회](/en/api-reference/endpoint/api-keys/scopes)
* [API 키 조회](/en/api-reference/endpoint/api-keys/get-by-id)
* [API 키 교체](/en/api-reference/endpoint/api-keys/rotate)
* [API 키 통계 보기](/en/api-reference/endpoint/api-keys/stats)
* [API 키 삭제](/en/api-reference/endpoint/api-keys/delete)

## 관련 가이드

* [API 레퍼런스 소개](/ko/api-reference/introduction)
* [액세스 제어](/en/security/access-control)
* [조직](./organizations.mdx)