IAM·API 토큰 도구

이 도구는 AI 에이전트가 Alpacon 워크스페이스에서 신원과 접근 권한을 관리할 수 있게 합니다. 사용자를 온보딩·오프보딩하고, 권한 그룹으로 조직하고, CI/CD나 자동화용 머신 애플리케이션을 등록하고, 프로그래밍 방식 접근을 위한 API 토큰을 발급합니다. “jane@example.com을 워크스페이스에 초대해줘”, “이 사용자를 온콜 그룹에 매니저로 추가해줘”, “서버 읽기 권한만 있는 API 토큰을 만들어줘” 같은 요청을 처리합니다.

모든 도구는 workspace(필수)와 region(선택, 기본값은 설정된 리전)을 받습니다. 아래 표에서는 이 공통 파라미터를 생략합니다.

요약

도구	카테고리	설명	접근 수준
`list_iam_users`	사용자	워크스페이스의 IAM 사용자 목록 조회	읽기 전용
`get_iam_user`	사용자	특정 사용자의 상세 정보 조회	읽기 전용
`create_iam_user`	사용자	새 사용자 계정 생성	추가적
`update_iam_user`	사용자	사용자 프로필 또는 활성 상태 수정	멱등적 쓰기
`delete_iam_user`	사용자	사용자 영구 삭제	파괴적
`invite_workspace_user`	사용자	워크스페이스 참여 이메일 초대 발송	추가적
`list_iam_groups`	그룹	워크스페이스의 IAM 그룹 목록 조회	읽기 전용
`create_iam_group`	그룹	새 권한 그룹 생성	추가적
`get_iam_group`	그룹	특정 그룹의 상세 정보 조회	읽기 전용
`update_iam_group`	그룹	그룹 표시 이름 또는 설명 수정	멱등적 쓰기
`delete_iam_group`	그룹	그룹 영구 삭제	파괴적
`list_iam_memberships`	멤버십	그룹 멤버십 목록 조회(그룹별 필터 가능)	읽기 전용
`add_iam_member`	멤버십	사용자를 역할과 함께 그룹에 추가	추가적
`remove_iam_member`	멤버십	그룹에서 사용자 제거	파괴적
`list_iam_applications`	애플리케이션	워크스페이스의 머신 애플리케이션 목록 조회	읽기 전용
`create_iam_application`	애플리케이션	새 머신 애플리케이션 생성	추가적
`get_iam_application`	애플리케이션	특정 애플리케이션의 상세 정보 조회	읽기 전용
`update_iam_application`	애플리케이션	애플리케이션 이름 또는 설명 수정	멱등적 쓰기
`delete_iam_application`	애플리케이션	애플리케이션 영구 삭제	파괴적
`assign_application_system_users`	애플리케이션	시스템 사용자를 애플리케이션의 서비스 계정으로 바인딩	멱등적 쓰기
`unassign_application_system_users`	애플리케이션	애플리케이션에서 시스템 사용자 해제	멱등적 쓰기
`list_api_tokens`	API 토큰	워크스페이스의 API 토큰 목록 조회	읽기 전용
`get_api_token`	API 토큰	특정 토큰의 상세 정보 조회	읽기 전용
`create_api_token`	API 토큰	새 API 토큰 생성	추가적
`update_api_token`	API 토큰	토큰 이름·상태·만료일·범위 수정	멱등적 쓰기
`delete_api_token`	API 토큰	토큰 영구 삭제	파괴적
`duplicate_api_token`	API 토큰	토큰 설정을 복제해 새 토큰 생성	추가적
`list_api_token_scopes`	API 토큰	사용 가능한 권한 범위 목록 조회	읽기 전용
`list_api_token_presets`	API 토큰	사용 가능한 범위 프리셋 목록 조회	읽기 전용

사용자

IAM 사용자 계정을 관리합니다. 그룹 멤버십은 사용자 레코드 자체에 포함되지 않으며, 그룹에 사용자를 추가·제거하려면 멤버십 도구를 사용해야 합니다.

list_iam_users

워크스페이스의 모든 IAM 사용자를 조회합니다. 각 사용자의 사용자명, 이메일, 활성 상태, 그룹 수(num_groups)를 반환합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`page`	integer	아니요	페이지네이션용 페이지 번호
`page_size`	integer	아니요	페이지당 사용자 수

예시

“이 워크스페이스의 활성 사용자를 모두 보여줘”

이 도구 자체에는 활성 상태 필터가 없으므로, 에이전트는 list_iam_users를 호출한 뒤 결과를 클라이언트 쪽에서 is_active 기준으로 걸러냅니다.

get_iam_user

특정 사용자의 상세 정보(이메일, 이름·성, 활성 상태, 그룹 수)를 ID로 조회합니다. 이 응답에는 그룹 멤버십이 포함되지 않으므로, 사용자가 속한 그룹을 확인하려면 list_iam_memberships를 사용합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`user_id`	string	예	IAM 사용자 ID(UUID)

예시

“550e8400-e29b-41d4-a716-446655440000 사용자의 프로필을 보여줘”

create_iam_user

새 IAM 사용자 계정을 생성합니다. 사용자명과 이메일이 필요하며, 계정은 기본적으로 활성 상태입니다. 그룹 배정은 생성 이후 add_iam_member로 별도 처리합니다.

접근 수준: 추가적

파라미터

파라미터	타입	필수	설명
`username`	string	예	새 사용자의 사용자명
`email`	string	예	새 사용자의 이메일 주소
`first_name`	string	아니요	이름
`last_name`	string	아니요	성
`is_active`	boolean	아니요	사용자 활성 여부(기본값: `true`)

예시

“jane, jane@example.com으로 사용자를 만들고 engineering 그룹에 추가해줘”

에이전트는 create_iam_user를 호출한 뒤, 반환된 사용자 ID와 engineering 그룹 ID로 add_iam_member를 호출합니다.

update_iam_user

기존 사용자의 이메일, 이름·성, 활성 상태를 수정합니다. 전달한 필드만 변경됩니다(부분 수정). 그룹 멤버십 변경은 이 도구가 아니라 add_iam_member/remove_iam_member로 처리합니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터	타입	필수	설명
`user_id`	string	예	수정할 IAM 사용자 ID
`email`	string	아니요	새 이메일 주소
`first_name`	string	아니요	새 이름
`last_name`	string	아니요	새 성
`is_active`	boolean	아니요	새 활성 상태

예시

“이메일이 old-contractor@example.com인 사용자를 비활성화해줘”

에이전트는 list_iam_users로 해당 사용자의 ID를 찾은 뒤, is_active=false로 update_iam_user를 호출합니다.

delete_iam_user

사용자 계정을 영구 삭제합니다. 되돌릴 수 없습니다. 접근만 중단하려면 이 도구 대신 update_iam_user에 is_active=false를 전달하세요.

접근 수준: 파괴적

파라미터

파라미터	타입	필수	설명
`user_id`	string	예	삭제할 IAM 사용자 ID

예시

“지난달에 퇴사한 계약직의 사용자 계정을 삭제해줘”

삭제는 영구적입니다. 나중에 필요할 수 있다면 update_iam_user로 비활성화해 기록을 보존하세요.

invite_workspace_user

워크스페이스 참여 이메일 초대를 발송합니다. create_iam_user와 달리 초대 대상은 이메일만으로 식별되며, 기존 IAM 사용자 레코드가 필요하지 않습니다. Auth0가 활성화된(클라우드) 배포에서만 사용할 수 있습니다.

접근 수준: 추가적

파라미터

파라미터	타입	필수	설명
`email`	string	예	초대를 발송할 이메일 주소

예시

“newhire@example.com을 이 워크스페이스에 초대해줘”

그룹

IAM 권한 그룹을 관리합니다. 그룹 이름은 소문자, 숫자, 하이픈, 언더스코어만 사용할 수 있습니다.

list_iam_groups

워크스페이스의 모든 IAM 그룹을 조회합니다. 그룹 이름, 설명, 멤버 정보를 반환합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`page`	integer	아니요	페이지네이션용 페이지 번호
`page_size`	integer	아니요	페이지당 그룹 수

예시

“이 워크스페이스의 IAM 그룹을 모두 보여줘”

create_iam_group

새 권한 그룹을 생성합니다. name은 ^[a-z0-9_-]+$ 패턴(소문자, 숫자, 하이픈, 언더스코어만)을 따라야 합니다. 생성 이후 add_iam_member로 사용자를 추가합니다.

접근 수준: 추가적

파라미터

파라미터	타입	필수	설명
`name`	string	예	그룹 이름(소문자, 숫자, 하이픈, 언더스코어만)
`display_name`	string	아니요	사람이 읽기 좋은 표시 이름
`description`	string	아니요	그룹 설명

예시

“on-call이라는 이름으로 표시 이름이 ‘On-call rotation’인 그룹을 만들어줘”

get_iam_group

특정 그룹의 상세 정보(이름, 표시 이름, 설명, 멤버 수 num_members, 멤버 이름)를 ID로 조회합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`group_id`	string	예	그룹 ID(UUID)

예시

“on-call 그룹에는 누가 있어?”

에이전트는 list_iam_groups로 그룹 ID를 찾은 뒤 get_iam_group을 호출해 멤버 이름을 확인합니다.

update_iam_group

그룹의 표시 이름 또는 설명을 수정합니다. 그룹 name 자체는 생성 후 서버에서 변경할 수 없습니다. 전달한 필드만 변경됩니다(부분 수정).

접근 수준: 멱등적 쓰기

파라미터

파라미터	타입	필수	설명
`group_id`	string	예	수정할 그룹 ID
`display_name`	string	아니요	새 표시 이름
`description`	string	아니요	새 그룹 설명

예시

“on-call 그룹 설명을 새 로테이션 일정에 맞게 수정해줘”

delete_iam_group

그룹을 영구 삭제합니다. 되돌릴 수 없으며, 이 그룹의 멤버십을 통해서만 부여됐던 권한을 멤버들이 잃게 됩니다.

접근 수준: 파괴적

파라미터

파라미터	타입	필수	설명
`group_id`	string	예	삭제할 그룹 ID

예시

“temp-project 그룹은 더 이상 필요 없으니 삭제해줘”

삭제는 영구적입니다. 이 그룹의 멤버십에만 의존하던 사용자는 즉시 해당 권한을 잃습니다.

멤버십

그룹 멤버십은 사용자·그룹과 별도의 리소스입니다. 각 멤버십 레코드는 사용자, 그룹, 역할을 연결합니다.

list_iam_memberships

워크스페이스의 그룹 멤버십을 조회합니다. group_id를 전달하면 특정 그룹의 멤버만 조회합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`group_id`	string	아니요	이 그룹으로 결과 필터링
`page`	integer	아니요	페이지네이션용 페이지 번호
`page_size`	integer	아니요	페이지당 멤버십 수

예시

“on-call 그룹의 멤버와 각자의 역할을 보여줘”

add_iam_member

멤버십 레코드를 생성해 사용자를 그룹에 추가합니다. 그룹 ID와 사용자 ID가 모두 필요합니다.

접근 수준: 추가적

파라미터

파라미터	타입	필수	설명
`group_id`	string	예	사용자를 추가할 그룹 ID
`user_id`	string	예	그룹에 추가할 사용자 ID
`role`	string	아니요	그룹 내 역할: `member`, `manager`, `owner`(기본값: `member`)

예시

“jane을 on-call 그룹의 매니저로 추가해줘”

에이전트는 jane의 사용자 ID와 그룹 ID를 확인한 뒤, role="manager"로 add_iam_member를 호출합니다.

remove_iam_member

멤버십 레코드를 삭제해 사용자를 그룹에서 제거합니다. 사용자 ID나 그룹 ID가 아니라 멤버십 ID가 필요하므로, 먼저 list_iam_memberships로 찾아야 합니다.

접근 수준: 파괴적

파라미터

파라미터	타입	필수	설명
`membership_id`	string	예	삭제할 멤버십 ID

예시

“jane을 on-call 그룹에서 제거해줘”

에이전트는 list_iam_memberships를 그룹으로 필터링해 jane의 멤버십 ID를 찾은 뒤, 그 ID로 remove_iam_member를 호출합니다.

애플리케이션

IAM 애플리케이션은 CI/CD 파이프라인, 모니터링 연동, 자동화, 외부 통합을 위한 머신 서비스 계정입니다. 서버의 시스템 사용자(OS 수준 계정)를 애플리케이션의 서비스 계정으로 바인딩할 수 있습니다.

list_iam_applications

워크스페이스의 모든 IAM 애플리케이션을 조회합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`page`	integer	아니요	페이지네이션용 페이지 번호
`page_size`	integer	아니요	페이지당 애플리케이션 수

예시

“이 워크스페이스에 설정된 머신 애플리케이션을 모두 보여줘”

create_iam_application

새 머신 애플리케이션을 생성합니다. 이름이 필요하며, service_type은 ci_cd, monitoring, automation, integration 중 하나여야 합니다(생략 시 서버가 integration으로 기본 처리).

접근 수준: 추가적

파라미터

파라미터	타입	필수	설명
`name`	string	예	새 애플리케이션 이름
`description`	string	아니요	애플리케이션 설명
`service_type`	string	아니요	`ci_cd`, `monitoring`, `automation`, `integration` 중 하나(서버 기본값: `integration`)

예시

“github-actions-deploy라는 이름으로 CI/CD 애플리케이션을 만들어줘”

get_iam_application

특정 애플리케이션의 상세 정보를 ID로 조회합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`app_id`	string	예	애플리케이션 ID(UUID)

예시

“github-actions-deploy 애플리케이션의 상세 정보를 보여줘”

update_iam_application

애플리케이션의 이름 또는 설명을 수정합니다. 전달한 필드만 변경됩니다(부분 수정).

접근 수준: 멱등적 쓰기

파라미터

파라미터	타입	필수	설명
`app_id`	string	예	수정할 애플리케이션 ID
`name`	string	아니요	새 애플리케이션 이름
`description`	string	아니요	새 애플리케이션 설명

예시

“github-actions-deploy 애플리케이션 이름을 gha-prod-deploy로 바꿔줘”

delete_iam_application

애플리케이션을 영구 삭제합니다. 되돌릴 수 없습니다.

접근 수준: 파괴적

파라미터

파라미터	타입	필수	설명
`app_id`	string	예	삭제할 애플리케이션 ID

예시

“old-jenkins-deploy 애플리케이션을 삭제해줘, Jenkins에서 이전 완료했어”

삭제는 영구적이며 되돌릴 수 없습니다.

assign_application_system_users

시스템 사용자(서버의 OS 수준 계정) 하나 이상을 애플리케이션의 서비스 계정으로 바인딩합니다. 시스템 사용자 ID가 최소 하나 필요합니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터	타입	필수	설명
`app_id`	string	예	시스템 사용자를 배정할 애플리케이션 ID
`system_user_ids`	array	예	바인딩할 시스템 사용자 ID(UUID) 목록. 최소 하나 필요

예시

“deploy 시스템 사용자를 github-actions-deploy 애플리케이션에 바인딩해줘”

unassign_application_system_users

애플리케이션에서 시스템 사용자 하나 이상을 해제합니다. 시스템 사용자 ID가 최소 하나 필요합니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터	타입	필수	설명
`app_id`	string	예	시스템 사용자를 해제할 애플리케이션 ID
`system_user_ids`	array	예	해제할 시스템 사용자 ID(UUID) 목록. 최소 하나 필요

예시

“deploy 시스템 사용자를 github-actions-deploy 애플리케이션에서 해제해줘”

API 토큰

API 토큰은 Alpacon API에 대한 프로그래밍 방식 접근 권한을 부여합니다. 기반이 되는 REST 엔드포인트는 API 토큰 문서를 참고하세요.

토큰 관리 도구(list_api_tokens, get_api_token, create_api_token, update_api_token, delete_api_token, duplicate_api_token)는 브라우저 로그인이 필요합니다. 정적 API 토큰을 쓰는 로컬 서버에서 호출하면 403 Forbidden을 반환하므로, 호스팅 서버(브라우저 OAuth)로 연결해 사용하세요. list_api_token_scopes와 list_api_token_presets는 이 제약을 받지 않습니다.

list_api_tokens

워크스페이스의 API 토큰을 조회합니다. 이름, 활성 상태, 원격 IP, 자유 텍스트 검색으로 필터링할 수 있습니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`page`	integer	아니요	페이지네이션용 페이지 번호
`page_size`	integer	아니요	페이지당 항목 수
`name`	string	아니요	정확한 토큰 이름으로 필터링
`enabled`	boolean	아니요	활성 상태로 필터링
`remote_ip`	string	아니요	토큰을 마지막으로 사용한 원격 IP로 필터링
`search`	string	아니요	이름, user agent, 원격 IP에 대한 자유 텍스트 검색
`ordering`	string	아니요	정렬 필드: `updated_at` 또는 `added_at`. 쉼표로 여러 필드 지정 가능, 내림차순은 `-` 접두사(서버 기본값: `-updated_at`)

예시

“이 워크스페이스에서 활성화된 API 토큰을 모두 보여줘”

에이전트는 enabled=true로 list_api_tokens를 호출합니다.

get_api_token

특정 API 토큰의 상세 정보(범위, 만료일, 활성 상태)를 ID로 조회합니다.

접근 수준: 읽기 전용

파라미터

파라미터	타입	필수	설명
`token_id`	string	예	조회할 API 토큰 ID

예시

“CI/CD 파이프라인 토큰에 어떤 범위가 설정돼 있는지 보여줘”

에이전트는 list_api_tokens로 토큰 ID를 찾은 뒤 get_api_token을 호출합니다.

create_api_token

새 API 토큰을 생성합니다. 범위는 scopes로 직접 지정하거나, 번들 단축키인 presets로 지정하거나(사용 가능한 키는 list_api_token_presets로 확인), 둘 다 지정할 수 있습니다. 프리셋은 명시적 범위와 병합되어 세분화된 범위 문자열로 저장됩니다.

접근 수준: 추가적

파라미터

파라미터	타입	필수	설명
`name`	string	예	API 토큰 이름
`scopes`	array	아니요	토큰의 권한 범위
`expires_at`	string	아니요	ISO 8601 형식의 만료 일시
`enabled`	boolean	아니요	토큰 활성 여부(서버 기본값: `true`)
`presets`	array	아니요	서버에서 해석되어 `scopes`와 병합되는 프리셋 범위 키

예시

“올해 말에 만료되는 읽기 전용 모니터링 토큰을 만들어줘”

에이전트는 list_api_token_scopes로 읽기 전용 모니터링 범위를 확인한 뒤, 해당 scopes와 expires_at="2026-12-31T23:59:59Z"로 create_api_token을 호출합니다.

update_api_token

기존 토큰의 이름, 활성 상태, 만료일, 범위를 수정합니다. 전달한 필드만 전송되며 나머지는 그대로 유지됩니다. presets는 생성 시에만 사용할 수 있어 이 도구에서는 지원하지 않습니다. expires_at과 clear_expires_at은 함께 쓸 수 없습니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터	타입	필수	설명
`token_id`	string	예	수정할 API 토큰 ID
`name`	string	아니요	새 토큰 이름
`enabled`	boolean	아니요	토큰 활성 상태 전환
`expires_at`	string	아니요	ISO 8601 형식의 새 만료 일시. `clear_expires_at`과 함께 쓸 수 없음
`clear_expires_at`	boolean	아니요	만료일을 제거해 토큰이 만료되지 않도록 함(기본값: `false`). `expires_at`과 함께 쓸 수 없음
`scopes`	array	아니요	대체할 범위 목록. 호출자의 권한 상한선에 대해 재검증됨

예시

“CI/CD 파이프라인 토큰을 비활성화해줘, 로테이션 중이야”

에이전트는 enabled=false로 update_api_token을 호출합니다.

delete_api_token

API 토큰을 영구 삭제하고 즉시 폐기합니다. 되돌릴 수 없습니다.

접근 수준: 파괴적

파라미터

파라미터	타입	필수	설명
`token_id`	string	예	삭제할 API 토큰 ID

예시

“더 이상 쓰지 않는 예전 스테이징 토큰을 삭제해줘”

삭제는 영구적입니다. 나중에 다시 필요할 수 있다면 update_api_token으로 enabled=false를 설정하거나, 삭제 전에 duplicate_api_token으로 복사본을 남겨두세요.

duplicate_api_token

기존 토큰의 설정(범위, 만료일)을 복제해 새 토큰을 만듭니다. name을 생략하면 서버가 이름을 자동 생성합니다(예: “Token (copy)”).

접근 수준: 추가적

파라미터

파라미터	타입	필수	설명
`token_id`	string	예	복제할 API 토큰 ID
`name`	string	아니요	복제된 토큰의 이름(생략 시 서버가 자동 생성)

예시

“원본을 로테이션하기 전에 CI/CD 파이프라인 토큰을 복제해줘”

list_api_token_scopes

API 토큰에 지정할 수 있는 권한 범위 목록을 조회합니다. create_api_token을 호출하기 전에 유효한 scopes 값을 확인할 때 사용합니다.

접근 수준: 읽기 전용

예시

“API 토큰에 지정할 수 있는 범위에는 어떤 게 있어?“

list_api_token_presets

사용 가능한 범위 프리셋(예: file_upload 같은 번들 단축키) 목록을 조회합니다. 개별 범위를 나열하는 대신 create_api_token의 presets로 전달할 수 있습니다.

접근 수준: 읽기 전용

예시

“API 토큰에 쓸 수 있는 프리셋 범위 번들에는 어떤 게 있어?”