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

# API Key 관리

> TokenHub API Key의 생성, 편집, 비활성화, 삭제와 접근 범위 설정 방법을 정리합니다.

API Key는 TokenHub 서비스에 접근하는 장기 유효 자격 증명입니다. [API Key Management](https://console.tencentcloud.com/tokenhub/apikey) 페이지에서 Key 생성, 편집, 활성화/비활성화, 삭제와 Key별 접근 범위 설정을 수행합니다.

<Warning>
  API Key는 장기 유효 자격 증명입니다. 요청 헤더에 포함해 사용하며, 안전하게 저장하고 주기적으로 교체하세요. 공개 환경에 노출되면 무단 사용으로 인한 보안 사고와 과금 피해가 발생할 수 있습니다.
</Warning>

<Note>
  단일 루트 계정에서 생성 가능한 API Key 기본 쿼터는 50개입니다. 추가가 필요하면 [티켓 제출](https://console.tencentcloud.com/workorder/category)로 쿼터 상향을 요청하세요.
</Note>

## API Key 목록 필드

| 필드            | 설명                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------- |
| Name          | 사용자 지정 API Key 이름입니다.                                                                     |
| Description   | 용도 식별을 위한 사용자 지정 설명입니다.                                                                   |
| Key           | TokenHub 호출 자격 증명입니다. 앞 5자리 + \*\*\* + 뒤 4자리로 마스킹 표시되며, 전체 값은 원클릭 복사를 지원합니다.              |
| Status        | 활성화/비활성화 스위치입니다. 비활성화된 Key를 사용하는 모든 API 요청은 거부됩니다.                                        |
| Key ID        | Key에 대응하는 식별자입니다. 비용 분배 청구서 조회에 사용합니다.                                                    |
| Access Scope  | Select All (모든 모델과 서비스 접근) 또는 Range (선택한 모델/서비스만 접근)입니다.                                  |
| Quota Limit   | Key의 사용량 상한입니다. 기본 비활성화 상태이며, 설정한 기간 내 사용량이 상한을 초과하면 이후 호출이 실패합니다.                        |
| Creation Time | Key 최초 생성 시각입니다.                                                                          |
| Actions       | Edit (접근 범위와 연결 모델/서비스 수정), Delete (영구 삭제, 2차 확인 필요, 삭제 즉시 해당 Key를 사용하는 모든 요청 실패)를 제공합니다. |

## Key 생성

<Steps>
  <Step title="API Key Management 페이지 이동">
    [API Key Management](https://console.tencentcloud.com/tokenhub/apikey) 페이지로 이동합니다.
  </Step>

  <Step title="Create a Key 클릭">
    페이지 상단에서 리전을 선택한 후 **Create a Key**를 클릭합니다.
  </Step>

  <Step title="Key 정보 설정">
    **Create a Key** 대화 상자에서 아래 항목을 설정합니다.

    | 항목                   | 설명                                                                                                              |
    | -------------------- | --------------------------------------------------------------------------------------------------------------- |
    | Key Name             | Key 이름입니다. 예: "Production Environment-Text Service", "Test Key"                                                 |
    | Description (선택)     | 용도 식별과 Key 구분을 위한 설명입니다.                                                                                        |
    | IP Address Allowlist | 이 Key에 접근을 허용할 IP 범위입니다. 네트워크 세그먼트를 지원하며 최대 50개까지 등록할 수 있습니다.                                                   |
    | Quota Limit          | 활성화하면 이 Key의 토큰 사용량이 상한에 도달했을 때 서비스를 중단합니다. 사용량 통계는 모델과 추론 서비스 엔드포인트를 구분하지 않습니다 (비용이 없는 패키지 제외).                |
    | Access Scope         | **Select All**은 계정의 모든 모델과 추론 서비스에 접근합니다. **Range**는 **Access Scope** 영역 좌우에서 접근 가능한 모델과 추론 서비스를 선택해 범위를 제한합니다. |

    **Quota Policy**는 daily, monthly, total 세 가지 주기를 지원합니다.

    | 정책          | 집계 방식                                                                                      |
    | ----------- | ------------------------------------------------------------------------------------------ |
    | Daily       | 캘린더 일 기준으로 집계하며 매일 00:00에 초기화합니다.                                                          |
    | Monthly     | 선택한 적용일 기준으로 집계하며 주기 종료 시 자동 초기화합니다. 예: 매월 3일 선택 시, 이번 달 3일 00:00부터 다음 달 2일 23:59까지 집계합니다. |
    | Total Quota | 사용량을 계속 누적하며 자동 초기화하지 않습니다.                                                                |

    <Warning>
      Quota Policy를 전환(예: daily에서 monthly로)하거나 월 적용일을 변경하면 기존 누적 사용량이 삭제되고 새 규칙으로 다시 누적됩니다.
    </Warning>
  </Step>

  <Step title="생성 완료 및 Key 저장">
    **Confirm**을 클릭해 생성을 완료합니다. 생성 후 표시되는 API Key를 반드시 복사해 안전하게 저장하세요.

    <Note>
      API Key 이름과 Key 값은 생성 후 변경할 수 없습니다.
    </Note>
  </Step>
</Steps>

## Key 편집

<Steps>
  <Step title="대상 Key 찾기">
    [API Key Management](https://console.tencentcloud.com/tokenhub/apikey) 페이지 상단에서 대상 Key가 속한 리전을 선택합니다.
  </Step>

  <Step title="Edit 클릭">
    대상 Key 오른쪽 **Actions** 열에서 **Edit**를 클릭합니다.
  </Step>

  <Step title="수정 및 저장">
    **Edit API Key** 대화 상자에서 설명이나 접근 범위를 수정한 후 **Confirm**을 클릭합니다.

    <Note>
      새로 지정한 범위로 전환하면 이전에 선택한 접근 범위는 무효화되며, 전환 후 범위가 우선 적용됩니다.
    </Note>
  </Step>
</Steps>

## Key 삭제

<Warning>
  삭제된 API Key는 복구할 수 없으며, 해당 Key를 사용하는 모든 서비스 호출이 즉시 실패합니다. 삭제 시 계정 본인 확인이 진행됩니다.
</Warning>

<Steps>
  <Step title="대상 Key 찾기">
    [API Key Management](https://console.tencentcloud.com/tokenhub/apikey) 페이지 상단에서 대상 Key가 속한 리전을 선택합니다.
  </Step>

  <Step title="Delete 클릭">
    대상 Key 오른쪽 **Actions** 열에서 **Delete**를 클릭합니다.
  </Step>

  <Step title="삭제 확인">
    **Confirm deleting API Key** 대화 상자에서 삭제 정보를 확인한 후 **Confirmed**를 클릭하면 삭제가 완료됩니다.
  </Step>
</Steps>

## 운영 권장 사항

| 권장 사항      | 설명                                             |
| ---------- | ---------------------------------------------- |
| 용도별 Key 분리 | 애플리케이션이나 환경(개발/테스트/프로덕션)별로 별도의 API Key를 생성합니다. |
| 최소 권한 원칙   | **Range** 설정으로 필요한 모델과 서비스만 접근하도록 제한합니다.       |
| 주기적 Key 교체 | 정기적으로 Key를 교체해 유출 위험을 줄입니다.                    |
| 미사용 Key 정리 | 더 이상 사용하지 않는 Key는 즉시 비활성화하거나 삭제합니다.            |
| 안전한 저장     | 생성 직후 Key를 안전한 위치에 저장합니다.                      |