---
title: "API Key 관리"
slug: "ai-mlxp-apikey"
description: "ML expert Platform의 Project/Workspace API Key 종류와 권한 모델, 발급·조회·삭제 방법, 서비스별 사용 방법을 설명합니다."
updated: 2026-09-17T09:07:14Z
published: 2026-09-17T09:07:14Z
canonical: "guide.ncloud-docs.com/ai-mlxp-apikey"
stale: true
---

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

# API Key 관리

VPC 환경에서 이용 가능합니다.

API Key는 ML expert Platform 콘솔에 로그인하지 않는 외부 프로그램이나 자동화 작업이 ML expert Platform의 리소스에 접근할 때 사용하는 인증 수단입니다. Model Registry CLI/SDK, Data Manager SDK, Pipelines SDK, 비공개로 운영하는 추론 엔드포인트 호출에 사용합니다.

이 가이드에서는 API Key의 종류와 권한 모델, 발급·조회·삭제 방법, 서비스별 사용 방법을 설명합니다.

## API Key 종류

API Key는 발급 범위에 따라 두 종류로 나뉩니다. 접근하려는 리소스가 어디에 속하는지에 따라 종류를 선택합니다.

| 종류 | 발급 위치 | 접근 대상 | 토큰 형식 |
| --- | --- | --- | --- |
| Project API Key | **Project > Home > API Key** 탭 | Project에 속한 모델, 추론 엔드포인트, Pipelines | `mlx-prj_`로 시작 |
| Workspace API Key | **Workspace > Dashboard > API Keys** 탭 | Workspace에 속한 모델, Data Manager 데이터셋 | `mlx-wrk_`로 시작 |

- 데이터셋은 Workspace 소유 리소스이므로 Workspace API Key로만 접근할 수 있습니다.
- 추론 엔드포인트와 Pipelines는 Project 소유 리소스이므로 Project API Key로만 접근할 수 있습니다.
- 하나의 API Key에 여러 권한을 함께 담을 수 있습니다. 서로 다른 Workspace 또는 Project의 리소스에 접근해야 하면 각각 API Key를 발급합니다.

참고

이전 버전에서 Workspace Dashboard에서 발급하던 계정 단위 API Key(`mlx-`로 시작)는 더 이상 새로 발급할 수 없습니다. 기존에 발급된 키는 만료 시각까지 계속 사용할 수 있으며, 만료 전에 이 가이드의 Project API Key 또는 Workspace API Key로 교체해 주십시오.

## 권한 모델

API Key는 **리소스 종류(Type)**, **권한 등급(Scope)**, **대상(Target)** 의 조합으로 권한을 지정합니다. API Key는 지정한 권한 범위 안에서만 동작하며 그 밖의 요청은 거부됩니다.

### Project API Key에 지정할 수 있는 권한

| 리소스 종류 | 권한 등급 | 설명 | 대상 지정 |
| --- | --- | --- | --- |
| Model | reader, writer | Project Model Registry의 모델 조회(reader), 생성·업로드·삭제(writer) | 모델 이름 |
| InferenceService | invoke | 추론 엔드포인트 호출 | InferenceService 이름 |
| LLMInferenceService | invoke | LLM 추론 엔드포인트 호출 | LLMInferenceService 이름 |
| KubeflowPipeline | writer | Pipelines API 호출(실험·실행 생성 포함) | 지정 불가(Project 전체) |

### Workspace API Key에 지정할 수 있는 권한

| 리소스 종류 | 권한 등급 | 설명 | 대상 지정 |
| --- | --- | --- | --- |
| Model | reader, writer | Workspace Model Registry의 모델 조회(reader), 생성·업로드·삭제(writer) | 모델 이름 |
| Dataset | reader, writer, admin | 데이터셋 읽기(reader), 생성·업로드·Tag/Branch 생성(writer), 데이터셋 삭제(admin) | 데이터셋 이름 |

권한 등급은 상위 등급이 하위 등급을 포함합니다(admin ⊇ writer ⊇ reader).

### 대상(Target) 지정 규칙

- 대상을 지정하면 이름이 일치하는 리소스에만 권한이 적용됩니다.
- 대상을 지정하지 않으면 해당 Project 또는 Workspace 안의 같은 종류 리소스 전체에 권한이 적용됩니다.
- 대상은 리소스 **이름** 기준으로 적용됩니다. 발급 시점에 없는 이름을 지정하면 나중에 같은 이름의 리소스가 생성될 때 권한이 적용됩니다.
- KubeflowPipeline은 대상을 지정할 수 없으며 항상 Project 전체에 적용됩니다.

주의

API Key의 권한, 유효기간, 종류는 발급 후 변경할 수 없습니다. 권한을 바꾸려면 기존 API Key를 삭제하고 새로 발급하십시오.

## API Key 관리 권한

API Key 목록 조회, 토큰 보기, 발급, 삭제는 해당 Project 또는 Workspace의 **Admin** 역할을 가진 사용자만 수행할 수 있습니다. API Key 목록에는 토큰 원문이 포함되므로 Writer, Reader 역할에는 API Key 탭이 표시되지 않습니다.

| 작업 | Project API Key | Workspace API Key |
| --- | --- | --- |
| 목록 조회·토큰 보기·발급·삭제 | Project Admin | Workspace Admin |

역할을 지정하는 방법은 [Members](/docs/ai-mlxp-pmembermngt)와 [Member Settings](/docs/ai-mlxp-membermngt)를 참조해 주십시오.

## API Key 발급

Project API Key를 발급하는 방법은 다음과 같습니다. Workspace API Key는 **Workspace > Dashboard > API Keys** 탭에서 같은 방법으로 발급합니다.

1. ML expert Platform 콘솔에서 Project를 선택하고 **Home > API Key** 탭으로 이동해 주십시오.
2. 목록 상단의 **Add**를 클릭해 주십시오. 발급된 키가 하나도 없으면 화면 가운데의 **추가** 버튼을 클릭해 주십시오.
3. **API Key 발급** 팝업 창에 다음 항목을 입력해 주십시오.
  - **API Key 이름**: 영소문자(a-z), 숫자(0-9), 하이픈(-)을 사용하여 63자 이하로 입력합니다. 영소문자 또는 숫자로 시작하고 끝나야 합니다.
  - **유효기간(일)**: 1~365 사이의 정수를 입력하거나, 입력란 오른쪽의 **7d**, **30d**, **90d**, **365d** 중 하나를 선택합니다. 기본값은 30일이며, 입력란 아래에 만료 예정 시각이 표시됩니다.
  - **설명**(선택): 사용처나 발급 대상을 256자 이하로 기록합니다.
  - **Permissions**: 리소스 종류, 권한 등급, 대상을 선택합니다. 권한 행을 더 추가하려면 **권한 추가** 버튼을 클릭합니다. 권한은 1개 이상 추가해야 하며, 같은 (리소스 종류, 권한 등급) 조합은 한 번만 추가할 수 있습니다.
4. **발급**을 클릭해 주십시오.
  - 발급 직후에는 목록의 상태가 **발급 중**으로 표시될 수 있습니다. 잠시 후 목록을 새로 고치면 토큰을 확인할 수 있습니다.

참고

- 유효기간의 최대값은 플랫폼 운영 설정에 따라 달라질 수 있습니다. 기본 상한은 365일입니다.
- 유효기간은 발급 시각부터 계산되며 연장할 수 없습니다. 만료 후에도 계속 사용해야 하면 만료 전에 새 API Key를 발급하고 사용처의 키를 교체하십시오.

## API Key 조회

**Home > API Key** 탭(Workspace는 **Dashboard > API Keys** 탭)의 목록에는 API Key 이름, Permissions, Expiration At(만료 시각), 상태, 발급자, 설명이 표시됩니다. 토큰 값을 확인하는 방법은 다음과 같습니다.

1. 목록에서 확인할 API Key 행의 **보기**를 클릭해 주십시오.
2. **API Key 보기** 창에서 이름, 발급자, 설명, 만료 시각, Permissions, 토큰을 확인하고 **확인**을 클릭해 주십시오.

토큰만 클립보드에 복사하려면 행의 **복사**를 클릭해 주십시오.

목록의 상태는 다음과 같습니다.

| 상태 | 설명 |
| --- | --- |
| 발급 중 | 토큰이 생성되는 중입니다. 잠시 후 다시 확인합니다. |
| 만료 임박 | 만료 시각이 가까운 API Key입니다. 교체를 준비합니다. |
| Expired | 유효기간이 지난 API Key입니다. 인증에 사용할 수 없으며 삭제할 수 있습니다. |
| 현재 없음 | Permissions 열에 표시되는 배지입니다. 권한의 대상으로 지정한 이름의 리소스가 현재 존재하지 않음을 뜻하며, 같은 이름의 리소스가 생성되면 권한이 적용됩니다. |

주의

토큰은 비밀번호와 같이 취급하십시오. 소스 코드 저장소, 채팅, 문서에 토큰을 남기지 말고, 유출이 의심되면 즉시 삭제하고 새로 발급하십시오.

## API Key 삭제

API Key를 삭제하면 해당 토큰으로 들어오는 요청은 즉시 거부됩니다.

1. **Home > API Key** 탭(Workspace는 **Dashboard > API Keys** 탭)으로 이동합니다.
2. 목록에서 삭제할 API Key 행의 체크박스를 선택합니다. 한 번에 하나만 선택할 수 있습니다.
3. 목록 상단의 **Delete**를 클릭합니다.
4. **API Key 삭제** 창에서 **삭제**를 클릭합니다.

만료된 API Key도 같은 방법으로 삭제합니다.

## API Key 사용

API Key는 HTTP 요청의 `Authorization` 헤더에 Bearer 토큰으로 전달합니다. 서비스별 사용 방법은 다음과 같습니다.

### 추론 엔드포인트 호출

추론 엔드포인트를 비공개로 운영하려면 `InferenceService` 또는 `LLMInferenceService`에 다음 어노테이션을 설정합니다. 어노테이션을 설정하지 않으면 엔드포인트는 인증 없이 호출할 수 있습니다.

```
metadata:
  annotations:
    mlx.navercorp.com/access-mode: restricted
```

비공개 엔드포인트는 다음 두 가지 방법으로 호출할 수 있습니다.

- 대상 `InferenceService`(또는 `LLMInferenceService`)에 `invoke` 권한이 있는 Project API Key
- 해당 Project 멤버의 kubeconfig 토큰

Project API Key로 호출하는 예는 다음과 같습니다. 엔드포인트 URL은 배포한 서비스의 `IngressRoute`에서 확인합니다. 추론 서비스 배포와 `IngressRoute` 설정은 [Serving](/docs/ai-mlxp-pserving)을 참조해 주십시오.

```
curl -H "Authorization: Bearer {API Key}" \
  -H "Content-Type: application/json" \
  https://{추론 엔드포인트 URL}/v1/models/{InferenceService 이름}:predict \
  --data-binary @input.json
```

참고

`InferenceService`의 `invoke` 권한은 predictor, transformer, explainer 구성 요소 전체에 적용됩니다. 어노테이션을 `restricted`에서 삭제하거나 `public`으로 바꾸면 다시 인증 없이 호출할 수 있습니다.

### Pipelines SDK

ML expert Platform 밖(로컬 PC, CI 서버 등)에서 Pipelines SDK로 파이프라인을 실행하려면 `KubeflowPipeline` `writer` 권한이 있는 Project API Key가 필요합니다.

```
import kfp

client = kfp.Client(
    host="https://{ML expert Platform 도메인}/pipeline",
    existing_token="{API Key}",
    namespace="p-{Project 이름}",
)
```

- `KubeflowPipeline` 권한이 없는 API Key로 호출하면 `403 APIKey does not grant KubeflowPipeline access` 오류가 발생합니다. 권한은 발급 후 추가할 수 없으므로 새 API Key를 발급하십시오.
- Workspace API Key는 Pipelines API에 사용할 수 없습니다.
- Project를 생성한 직후에는 `403 project serviceaccount not provisioned` 오류가 발생할 수 있습니다. 잠시 후 다시 시도하십시오.

파이프라인 작성 방법은 [Pipelines](/docs/ai-mlxp-ppipelines)를 참조해 주십시오.

### Model Registry CLI/SDK

Model Registry CLI/SDK는 환경 변수 `MLX_APIKEY` 또는 `mlx configure` 명령으로 API Key를 설정합니다.

```
export MLX_ENDPOINT_URL="https://{ML expert Platform 도메인}"
export MLX_APIKEY="{API Key}"
```

- Project의 모델은 `Model` 권한이 있는 Project API Key, Workspace의 모델은 `Model` 권한이 있는 Workspace API Key를 사용합니다.
- 모델 조회·다운로드에는 `reader`, 모델·버전 생성과 파일 업로드·삭제에는 `writer` 권한이 필요합니다.
- 추론 서비스가 Model Registry의 모델을 내려받을 때 사용하는 `storage-config` Secret에도 `Model` `reader` 권한이 있는 API Key를 넣습니다.

자세한 사용 방법은 [Model Registry](/docs/ai-mlxp-pmodelregistry)를 참조해 주십시오.

### Data Manager SDK

Data Manager SDK는 `Dataset` 권한이 있는 Workspace API Key로 로그인합니다.

```
from mlx.sdk.data import login

login("{API Key}", "{ML expert Platform 도메인}")
```

| 작업 | 필요한 권한 등급 |
| --- | --- |
| 데이터셋 목록·상세 조회, 다운로드 | reader |
| 데이터셋 생성, 업로드, Tag 및 Branch 생성 | writer |
| 데이터셋 삭제 | admin |

특정 데이터셋만 허용하려면 권한의 대상에 데이터셋 이름을 지정합니다. 자세한 사용 방법은 [Data Manager](/docs/ai-mlxp-datamanager)를 참조해 주십시오.

## API Key와 kubeconfig 비교

ML expert Platform은 API Key 외에 Project 단위 `kubeconfig`도 제공합니다. 용도에 맞게 선택합니다.

| 항목 | API Key | kubeconfig |
| --- | --- | --- |
| 용도 | 외부 프로그램·자동화 작업이 Model Registry, Data Manager, Pipelines, 추론 엔드포인트에 접근 | 사용자가 `kubectl`로 Project Namespace에 워크로드 생성·조회 |
| 권한 기준 | 발급 시 지정한 리소스 종류·권한 등급·대상 | 사용자의 Project 멤버 역할(Admin/Writer/Reader) |
| 발급 주체 | Project 또는 Workspace Admin | Project 멤버 본인 |
| 유효기간 | 1~365일(기본 30일) | 1일~운영 설정 상한(기본 90일) |
| 만료 전 폐기 | 삭제하면 즉시 무효 | 불가(멤버에서 제외하면 권한만 회수) |

kubeconfig 발급 방법은 [Overview](/docs/ai-mlxp-pscreen)를 참조해 주십시오.

## 문제 해결

| 증상 | 원인 | 해결 방법 |
| --- | --- | --- |
| 콘솔에 API Key 탭이 보이지 않음 | Admin 역할이 아님 | Project 또는 Workspace Admin에게 발급을 요청 |
| 401 오류 | 토큰 오타, 만료된 API Key, 삭제된 API Key | 콘솔에서 상태를 확인하고 필요하면 새로 발급 |
| 403 오류 | 요청한 리소스에 대한 권한 또는 대상이 API Key에 없음, 종류가 다른 API Key 사용(예: Workspace API Key로 Pipelines 호출) | 필요한 권한과 대상을 담은 올바른 종류의 API Key를 새로 발급 |
| 데이터셋 삭제가 403으로 거부됨 | `Dataset` 권한 등급이 admin이 아님 | `Dataset` `admin` 권한을 담은 Workspace API Key를 발급 |
| 발급 직후 토큰이 보이지 않음 | 토큰 생성 중 | 잠시 후 목록을 새로 고침 |