API 접근 토큰

API 접근 토큰을 사용하면 CI/CD 파이프라인, 자동화 스크립트 등 여러 연동에서 Alpacon API에 프로그래밍 방식으로 접근할 수 있습니다. 각 토큰은 접근 범위로 허용되는 리소스와 작업을 제한하고, ACL 규칙으로 명령어, 파일 작업, 서버 접근을 추가로 제한할 수 있습니다.

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

API 토큰 위치

우측 상단의 프로필 드롭다운을 열고 내 API 토큰을 클릭해 토큰을 관리합니다.

토큰 목록

각 토큰의 이름, 접근 범위 수, 유효 기간, 마지막 업데이트를 확인할 수 있습니다.

토큰 생성

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

접근 범위

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

사용 가능한 리소스

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

와일드카드

접근 범위의미
*모든 리소스의 모든 작업 (전체 접근)
{resource}:*한 리소스의 모든 작업
*:{action}모든 리소스의 한 작업

와일드카드는 본인 권한이 그 와일드카드 자체를 덮을 때만 받으므로, *는 워크스페이스 superuser만 쓸 수 있습니다. 형식에서 자세히 다룹니다.

접근 범위 선택

접근 범위는 두 단계로 선택합니다. 먼저 리소스를 선택하고, 그다음 해당 리소스의 작업을 선택합니다. 전체 접근을 선택하면 와일드카드 * 접근 범위가 부여됩니다.

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

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

빠른 프리셋

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

토큰 상세

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

토큰 관리

  • 우측 상단의 토글 버튼으로 토큰을 활성화하거나 비활성화할 수 있습니다.
  • 다음 항목을 관리할 수 있습니다.
기능설명
토큰 업데이트토큰의 이름과 만료일을 수정합니다. (접근 범위는 아래처럼 인라인으로 편집합니다.)
토큰 삭제토큰을 영구적으로 삭제합니다.
토큰 복제동일한 접근 범위, ACL 규칙, 만료일로 토큰을 복제합니다.
허용된 명령토큰으로 실행할 수 있는 명령어를 제한합니다.
허용된 파일 작업토큰으로 수행할 수 있는 파일 작업을 제한합니다.
허용된 서버토큰으로 접근할 수 있는 서버를 제한합니다.

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

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

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

토큰 복제

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

ACL 규칙

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

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

허용된 명령

허용된 명령은 이 토큰으로 실행할 수 있는 명령어를 제한합니다.

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

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

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

명령어 항목은 root로 실행될 명령이 아니라 제출한 명령줄과 비교되므로, 권한이 필요한 명령의 항목에는 sudo 접두어가 포함되어야 하고 끝의 *는 인자를 최소 1개 요구합니다. sudo 명령의 항목을 작성하기 전에 명령 패턴과 sudo를 확인하세요.

허용된 파일 작업

허용된 파일 작업은 이 토큰으로 수행할 수 있는 파일 전송 작업(업로드/다운로드)을 제한합니다.

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

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

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

허용된 서버

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

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

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

보안 모범 사례

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