---
title: "개인 API 토큰 관리"
description: "Alpacon API를 제한된 권한으로 호출할 개인 API 접근 토큰을 만듭니다. 접근 범위와 만료일을 설정하고 서버 ACL 규칙을 검토하세요. 기존 토큰은 명령·파일 권한을 유지할 수 있지만 새 개인 토큰에는 부여할 수 없습니다. 자동화와 CI에는 서비스 토큰을 사용합니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# 개인 API 토큰 관리

<span id="api-토큰-위치" />

# 개인 API 토큰 관리

<span id="api-접근-토큰" />

Alpacon API를 제한된 권한으로 호출할 개인 API 토큰을 만듭니다.

## 토큰의 접근 범위

개인 API 토큰으로 Alpacon API를 호출할 수 있습니다. 각 토큰은 **접근 범위**로 허용되는 리소스와 작업을 제한하고, **ACL 규칙**으로 명령어, 파일 작업, 서버 접근을 추가로 제한할 수 있습니다.

이 토큰은 대화형 로그인이나 비밀번호 없이 Alpacon API에 접근할 수 있으므로 **절대 외부에 공유하지 마세요.**

새 개인 API 토큰에는 명령어 실행이나 파일 전송 범위를 부여할 수 없습니다. 해당 범위를 이미 가진 토큰은 작업 세션 없이 계속 사용할 수 있습니다. 자동화와 CI에는 [서비스 토큰](/use/iam/applications/service-tokens/)을 쓰세요.

---

## 개인 API 토큰 위치

왼쪽 사이드바 맨 아래의 계정 카드를 클릭한 다음 **내 API 토큰**을 선택해 토큰을 관리합니다.

---

## 토큰 목록

목록에서 각 토큰의 이름, 접근 범위 수, 만료일, 마지막 변경 시각을 확인할 수 있습니다.

### 토큰 생성

1. **추가** 버튼을 클릭합니다.
2. **토큰 이름**을 설정합니다.
3. **만료일**을 설정합니다 (7일, 30일, 90일, 1년, 직접 설정). 새로 만드는 토큰에는 모두 만료일이 있으며, 워크스페이스의 토큰 최대 기간보다 늦게 잡을 수 없습니다.
4. **접근 범위**를 선택하여 토큰이 접근할 수 있는 리소스와 작업을 정의합니다.
5. **생성**을 클릭합니다.
6. 생성된 토큰 키가 상세 화면에 표시됩니다. **반드시 복사하여 안전한 위치에 저장하세요**. 페이지를 떠나면 다시 조회할 수 없습니다.

---

## 접근 범위

접근 범위는 개인 API 토큰이 수행할 수 있는 리소스와 작업을 정의합니다. 형식은 `{resource}:{action}`입니다.

### 사용 가능한 리소스

토큰이 가질 수 있는 리소스와 액션 전체는 [접근 범위 레퍼런스](/reference/scopes/)에 각 항목이 여는 것과 어떤 ACL로 좁혀지는지까지 정리돼 있습니다. 접근 범위 선택 UI에는 본인 역할이 부여할 수 있는 항목만 나타납니다.

### 와일드카드

| 접근 범위 | 의미 |
| --- | --- |
| `{resource}:*` | 한 리소스의 모든 작업 |
| `*:{action}` | 모든 리소스의 한 작업 |

와일드카드는 본인 권한이 그 와일드카드 자체를 덮을 때만 받습니다. 개인 API 토큰에는 `*`나 `command:*`, `uploaded_file:*`, `downloaded_file:*`, `*:create`처럼 명령 실행이나 파일 전송을 덮는 와일드카드를 줄 수 없습니다. 이런 와일드카드를 가진 채 발급된 토큰은 그대로 유지됩니다. [형식](/reference/scopes/#형식)에서 자세히 다룹니다.

### 접근 범위 선택

접근 범위는 두 단계로 선택합니다. 먼저 리소스를 선택하고, 그다음 해당 리소스의 작업을 선택합니다. 한 리소스의 작업을 모두 주려면 그 리소스에서 **모든 작업**을 고르면 됩니다. 개인 API 토큰에서는 **Command**, **Uploaded file**, **Downloaded file**에 이 선택지가 없습니다.

선택된 접근 범위는 작업 유형별로 색상이 구분된 태그로 표시됩니다.

> 필요에 맞는 최소한의 접근 범위만 선택하세요.

### 빠른 프리셋

토큰 생성 시 각 접근 범위를 개별로 고르는 대신, 일반적인 워크플로용 접근 범위 묶음인 **빠른 프리셋**을 적용할 수 있습니다. 프리셋은 생성 시점에만 제공되며, 기존 토큰에서는 접근 범위를 직접 편집합니다. 프리셋 목록과 각 프리셋이 부여하는 항목은 [접근 범위 레퍼런스](/reference/scopes/#프리셋)에 있습니다.

---

## 토큰 상세

목록에서 토큰을 클릭하면 상세 화면으로 이동합니다.

### 토큰 관리

- 우측 상단의 **토글 버튼**으로 토큰을 활성화하거나 비활성화할 수 있습니다.
- 다음 항목을 관리할 수 있습니다.

| 기능 | 설명 |
| --- | --- |
| **토큰 업데이트** | 토큰의 **이름과 만료일**을 수정합니다. (접근 범위는 아래처럼 인라인으로 편집합니다.) |
| **토큰 삭제** | 토큰을 영구적으로 삭제합니다. |
| **토큰 복제** | 동일한 접근 범위, ACL 규칙, 만료일로 토큰을 복제합니다. |
| **허용된 명령** | 토큰으로 실행할 수 있는 명령어를 제한합니다. |
| **허용된 파일 작업** | 토큰으로 수행할 수 있는 파일 작업을 제한합니다. |
| **허용된 서버** | 토큰으로 접근할 수 있는 서버를 제한합니다. |

**접근 범위 편집:** 상세 페이지에서 접근 범위를 인라인으로 변경한 뒤 **저장**을 클릭해 적용합니다.

**사용 기록:** 상세 페이지의 **활동 로그** 화면에서 이 토큰의 사용 이력을 볼 수 있습니다.

토큰이 **비활성** 상태인 동안에는 ACL 규칙의 **추가** 버튼이 비활성화됩니다. 항목을 추가하려면 먼저 토큰을 다시 활성화하세요.

### 토큰 복제

**복제**를 클릭하면 토큰의 복사본이 생성됩니다. 복제된 토큰은 원본의 접근 범위, ACL 규칙, 만료일을 상속합니다. 새 토큰 이름에는 "(copy)" 접미사가 붙습니다.

---

## ACL 규칙

ACL(Access Control List) 규칙은 접근 범위 수준의 권한을 넘어 토큰이 수행할 수 있는 작업을 세밀하게 제어합니다. 각 ACL 유형은 토큰 사용의 특정 측면을 제한합니다.

Command/File/Server ACL은 해당 기능에 필요한 접근 범위가 토큰에 먼저 부여된 경우에만 의미가 있습니다. 관련 접근 범위가 없다면 ACL에 항목이 등록되어 있어도 해당 기능에는 **접근할 수 없습니다**. 반대로 관련 접근 범위는 있지만 ACL 유형에 항목이 등록되지 않은 경우 그 기능에 대한 **접근이 허용되지 않습니다**. 접근을 허용하려면 필요한 접근 범위를 부여한 뒤 해당 ACL 유형에 최소 1개 이상의 항목을 등록하세요. 리소스마다 어떤 ACL 유형이 적용되는지는 [접근 범위 참고](/reference/scopes/#전체-리소스)의 객체 범위 열에서 확인할 수 있습니다.

### 허용된 명령

**허용된 명령**은 이 토큰으로 실행할 수 있는 명령어를 제한합니다. 명령 접근 범위를 이미 가진 개인 API 토큰에 적용됩니다.

- 명령어를 **등록하지 않은 경우**: 명령어 실행 불가
- 명령어를 **1개라도 등록한 경우**: 등록된 명령어만 실행 가능

각 명령어 항목은 다음 필드로 구성됩니다.

| 필드 | 설명 |
| --- | --- |
| **명령어** | 허용할 명령어. 와일드카드(`*`) 지원. |
| **유저명** | 명령어를 실행할 사용자. `*`는 모든 사용자, 빈값은 토큰 소유자. |
| **그룹명** | 명령어 실행의 그룹 컨텍스트. `*`는 모든 그룹, 빈값은 제한 없음. |

명령어 항목은 root로 실행될 명령이 아니라 제출한 명령줄과 비교되므로, 권한이 필요한 명령의 항목에는 `sudo` 접두어가 포함되어야 하고 끝의 ` *`는 인자를 최소 1개 요구합니다. `sudo` 명령의 항목을 작성하기 전에 [토큰 명령어 매칭](/reference/tokens/command-patterns/)을 확인하세요.

### 허용된 파일 작업

**허용된 파일 작업**은 이 토큰으로 수행할 수 있는 파일 전송 작업(업로드/다운로드)을 제한합니다. 파일 전송 접근 범위를 이미 가진 개인 API 토큰에 적용됩니다.

- 파일 작업을 **등록하지 않은 경우**: 파일 작업 수행 불가
- 파일 작업을 **1개라도 등록한 경우**: 등록된 파일 작업만 수행 가능

각 파일 작업 항목은 다음 필드로 구성됩니다.

| 필드 | 설명 |
| --- | --- |
| **경로** | 허용할 파일 경로. 와일드카드(`*`) 지원. |
| **작업** | 작업 유형: 업로드, 다운로드, 또는 전체. |
| **유저명** | 파일 작업을 수행할 사용자. `*`는 모든 사용자, 빈값은 토큰 소유자. |
| **그룹명** | 파일 작업의 그룹 컨텍스트. `*`는 모든 그룹, 빈값은 제한 없음. |

### 허용된 서버

**허용된 서버**는 이 토큰으로 접근할 수 있는 서버를 제한합니다.

- 서버를 **등록하지 않은 경우**: 서버 접근 불가
- 서버를 **1개라도 등록한 경우**: 등록된 서버만 접근 가능

서버 목록에서 선택하여 추가합니다.

---

## 보안 모범 사례

- **최소 권한 원칙**: 토큰의 용도에 필요한 접근 범위만 부여하세요.
- **정기적인 토큰 교체**: 만료일을 설정하고 만료 전에 새 토큰을 생성하세요.
- **ACL 규칙 설정**: 허용된 명령, 파일 작업, 서버를 제한하여 위험을 최소화하세요.
- **토큰 안전 보관**: 암호화된 시크릿 저장소를 사용하세요. CI/CD 같은 자동화 작업에는 서비스 토큰을 사용하세요.
- **미사용 토큰 정리**: 더 이상 필요하지 않은 토큰은 비활성화하거나 삭제하세요.

Source: https://docs.alpacax.com/ko/use/settings/api-tokens/