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

# API Key 관리하기

> VESSL Cloud 인퍼런스 엔드포인트 요청을 인증하는 API Key를 직접 생성하고 폐기하는 방법을 안내해요.

![API Keys 페이지: New API Key 버튼과 함께 이름, 마스킹된 키, 상태, 생성일, 만료일, 마지막 수정자를 보여 주는 키 목록 표. 폐기된 키는 아래쪽에 흐리게 표시됨](https://mintcdn.com/dora/SronkP2zLUPqOXHN/images/inference-api-keys-list.png?fit=max\&auto=format\&n=SronkP2zLUPqOXHN\&q=85\&s=66c8317f201752d2df038fbc6365d82a)

예시: 활성 키와 폐기된 키가 함께 표시된 API Keys 페이지

VESSL Cloud 인퍼런스 엔드포인트로 보내는 모든 요청에는 API Key가 들어가요. 이 키는 VESSL Cloud의 **Settings** → **API Keys**에서 직접 만들고 관리할 수 있어서, 필요한 순간에 바로 발급하고 더 이상 쓰지 않으면 바로 폐기(revoke)할 수 있어요.

API Key는 조직(Organization) 단위로 관리돼요. **API Keys** 페이지에는 조직의 모든 키가 표시되고, 키마다 마지막으로 생성, 이름 변경, 폐기한 멤버가 기록돼요.

## API Key 만들기

1. **Settings**를 열고 **Organization** 아래 **API Keys**를 선택하세요.
2. **New API Key**를 클릭하세요.
3. **API Key name**을 입력하세요(최대 128자). `prod-chat-service`, `eval-pipeline`처럼 어디에 쓰는 키인지 알 수 있는 이름을 쓰면 나중에 구분하기 쉬워요.
4. 만료 시점을 정하세요. **Set Expiration Date**는 기본으로 켜져 있고 기본값은 **30 days**예요. **7**, **60**, **90 days** 중에서 고를 수도 있어요. 키는 선택한 기간의 마지막 날이 끝나는 자정(로컬 시간 기준)에 만료되고, 정확한 시각은 선택 상자 아래에 표시돼요. 만료되지 않는 키가 필요하면 토글을 끄세요. 이 경우 직접 폐기하기 전까지 키가 계속 유효해요.
5. **Create**를 클릭하세요. 전체 키가 담긴 **Save your API Key** 창이 열려요.
6. 복사 버튼을 클릭해 키를 복사하세요. 키를 먼저 확인하려면 눈 아이콘을 클릭하세요.
7. 시크릿 매니저(secret manager) 같은 안전한 곳에 키를 저장하세요.
8. **Done**을 클릭하세요.

> [!WARNING]
>
> 전체 키는 **Save your API Key** 창에서 한 번만 보여요. VESSL Cloud는 키를 다시 보여 줄 수 있는 형태로 저장하지 않아서, 창을 닫은 뒤에는 앞부분만 확인할 수 있어요. 키를 잃어버렸다면 새 키를 만들고 기존 키를 폐기하세요.

> [!TIP]
>
> 모델 페이지에서 **Get started**를 클릭하면 열리는 퀵스타트(quickstart) 가이드의 첫 단계에 **API Keys** 페이지로 가는 링크가 있어요. 키 생성부터 첫 요청까지 한 번에 진행할 수 있어요.

## API Key 사용하기

`https://inference.cloud.vessl.ai/v1`로 보내는 모든 요청의 `Authorization` 헤더에 `Bearer <api-key>` 형식으로 키를 넣으세요. 먼저 키를 `VESSL_API_KEY` 환경 변수로 설정하세요.

```bash theme={null}
export VESSL_API_KEY="<api-key>"
```

```bash cURL theme={null}
curl https://inference.cloud.vessl.ai/v1/chat/completions \
  -H "Authorization: Bearer $VESSL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {"role": "user", "content": "Hello! Who are you?"}
    ]
  }'
```

```python Python theme={null}
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://inference.cloud.vessl.ai/v1/chat/completions",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['VESSL_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps({
        "model": "<model-id>",
        "messages": [
            {"role": "user", "content": "Hello! Who are you?"},
        ],
    }).encode(),
)

with urllib.request.urlopen(request, timeout=120) as response:
    body = json.load(response)

print(body["choices"][0]["message"]["content"])
```

```typescript TypeScript theme={null}
const response = await fetch("https://inference.cloud.vessl.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VESSL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "<model-id>",
    messages: [
      { role: "user", content: "Hello! Who are you?" },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status} ${await response.text()}`);
}

const body = await response.json();
console.log(body.choices[0].message.content);
```

엔드포인트 정보와 모델 ID 확인 방법은 [첫 요청 보내기](https://docs.cloud.vessl.ai/ko/inference/send-requests.md)를 참고하세요.

API Key는 비밀번호처럼 다루세요. 환경 변수나 시크릿 매니저에 보관하고, 소스 코드 저장소에 커밋하거나 클라이언트 코드에 넣지 마세요.

## API Keys 목록

활성 키가 먼저 표시되고, 같은 상태 안에서는 최신 키가 먼저 표시돼요.

> [!NOTE]
>
> 목록에는 다음 열이 표시돼요.
>
> * **Name**: 키에 붙인 이름
> * **Key**: 키의 앞부분 몇 글자와 마스킹(masking) 처리된 나머지 부분. 전체 키는 여기서 볼 수 없어요.
> * **Status**: **Active**, **Expired**, **Revoked** 중 하나. [API Key 상태](#api-key-상태)를 참고하세요.
> * **Created**: 키를 만든 날짜
> * **Expires**: 만료 일시. 만료일이 없는 키는 **Never**, 폐기된 키는 `-`로 표시돼요.
> * **Last edited by**: 키를 마지막으로 생성, 이름 변경, 폐기한 멤버

만료되거나 폐기된 키는 30일 동안 흐리게 표시된 채 목록에 남고, 그 뒤에는 목록에 표시되지 않아요.

## 권한

| 작업 | 할 수 있는 사람 |
| - | - |
| 키 조회, 생성 | 조직에 속한 누구나 |
| 이름 변경, 폐기 | **Organization admin**만 |

멤버에게는 목록의 **⋮** 메뉴가 보이지 않아요. 멤버인데 키가 유출된 것 같다면 Organization admin에게 폐기를 요청하세요. admin 작업 절차는 [API Key 이름 변경과 폐기](https://docs.cloud.vessl.ai/ko/admin/api-keys/overview.md)를 참고하세요.

## API Key 이름 바꾸기

1. 키 행 끝의 **⋮** 메뉴를 열고 **Edit**를 선택하세요.
2. **API Key name**을 수정하세요.
3. **Edit**를 클릭하세요.

바꿀 수 있는 건 이름뿐이에요. 만료일은 키를 만들 때 정해지고 이후에는 바꿀 수 없어요. 만료일을 다르게 하려면 새 키를 만들고 기존 키를 폐기하세요. [트래픽 끊김 없이 API Key 바꾸기](#트래픽-끊김-없이-api-key-바꾸기)를 참고하세요.

## API Key 폐기하기

더 이상 쓰지 않는 키나 유출이 의심되는 키는 폐기하세요.

1. 키 행 끝의 **⋮** 메뉴를 열고 **Revoke**를 선택하세요.
2. 확인을 위해 키 이름을 입력하세요.
3. **Revoke**를 클릭하세요.

폐기는 되돌릴 수 없어요. 해당 키로 보내는 요청은 1분 안에 거부되기 시작해요. 폐기된 키는 **Revoked** 상태로 30일 동안 목록에 남고, 그 뒤에는 목록에 표시되지 않아요.

**⋮** 메뉴는 모든 행에 보이지만, 만료되거나 폐기된 키에서는 비활성화돼서 수정하거나 다시 폐기할 수 없어요. 이름 변경과 폐기는 Organization admin만 할 수 있어요.

## 트래픽 끊김 없이 API Key 바꾸기

트래픽을 끊지 않고 새 키로 바꾸려면, 새 키를 먼저 만들고 애플리케이션을 모두 옮긴 뒤 기존 키를 폐기하세요.

1. 새 키를 만드세요. [API Key 만들기](#api-key-만들기)를 참고하세요.
2. 기존 키를 쓰는 모든 애플리케이션이 새 키를 보내도록 업데이트하세요.
3. 기존 키로 들어오는 트래픽이 없어지면 기존 키를 폐기하세요. [API Key 폐기하기](#api-key-폐기하기)를 참고하세요.

만료일이 있는 키를 쓰면 정기적으로 키를 바꾸기 쉬워요. 기존 키가 만료되기 며칠 전에 새 키를 만들어 애플리케이션을 옮기고, 기존 키는 그대로 만료되게 두면 돼요.

## API Key 상태

| 상태 | 의미 | 요청 가능 여부 |
| - | - | - |
| **Active** | 유효한 키예요. | 가능 |
| **Expired** | 만료일이 지난 키예요. | 불가 |
| **Revoked** | 폐기된 키예요. | 불가 |

만료되거나 폐기된 키로 요청하면 인증 오류가 발생해요. 새 키를 만들고 애플리케이션이 그 키를 쓰도록 바꾸세요.


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