API 레퍼런스
로그인
본문으로 건너뛰기

API 키 관리와 폐기

CLI와 MCP와 GitHub Action은 API 키로만 인증합니다, 키 형식, 권한, 만료, 발급과 폐기, 안전하게 보관하는 방법을 설명합니다

CLI와 MCP 서버와 GitHub Action은 API 키로만 인증합니다, 키는 워크스페이스 하나에 묶이고 권한은 실행과 조회(run) 또는 조회만(read) 두 가지입니다

키 형식

xci_live_<43자>_<6자>
  • 앞 43자는 무작위, 뒤 6자는 CRC32 체크섬입니다, 서버는 데이터베이스를 읽기 전에 체크섬부터 확인합니다
  • 서버는 키의 SHA-256 해시만 저장합니다, 발급 응답에서 한 번 보인 뒤에는 어디서도 다시 볼 수 없습니다
  • 목록에는 앞 12자와 뒤 4자만 보입니다(예 xci_live_3fK…Pm81)
  • 옛 xeno_ 접두사 키는 종료되었고 401 invalid_api_key입니다

권한

권한콘솔 표시할 수 있는 일
run실행과 조회잡 제출과 취소, 업로드, 배치와 레시피 쓰기, 그리고 아래 조회 전부
read조회만잡, 로그, 결과물, 사용량, 비용, 한도, 환경 조회, GET 요청만

read 키로 GET이 아닌 요청을 보내면 403 insufficient_permission입니다, 어떤 키로도 결제, 충전, 키 발급, 멤버와 워크스페이스 관리는 할 수 없습니다(403 console_only), 키는 자기 워크스페이스 밖을 볼 수 없습니다

키 발급하기

소유자와 관리자는 모든 워크스페이스에서, 개발자는 배정된 워크스페이스에서만 발급합니다

  1. 콘솔 API 키에서 키 추가를 누릅니다
  2. 키 이름(80자 이하)을 넣고 워크스페이스를 고릅니다
  3. 권한에서 실행과 조회 또는 조회만을 고릅니다
  4. 만료에서 만료 없음, 30일, 90일, 1년 중 하나를 고릅니다
  5. 키 생성을 누르면 키 값이 한 번 보입니다, 환경 변수로 쓰기로 복사해 안전한 곳에 넣습니다

API로는 API 키 발급을 씁니다

curl -X POST "https://xenoci.com/api/runner/v1/organizations/org_7Kq2m9ZtP3/workspaces/wrk_3fK9Qm2Zp8/api-keys" \
  --cookie "xci_console=$SESSION" \
  -H "Origin: https://xenoci.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci","permission":"run","expires_in_days":90}'

키 쓰기

어디서방법
CLI사람이 터미널에서 xenocast login(키를 가린 입력)으로 저장하거나 환경 변수 XENOCI_API_KEY, 환경 변수가 저장된 키보다 우선
MCP 서버MCP 설정의 env에 XENOCI_API_KEY, 또는 CLI가 저장한 키를 그대로 사용
GitHub Action저장소 시크릿 XENOCI_API_KEY를 with: api-key로 전달
직접 호출Authorization: Bearer xci_live_… 헤더
xenocast login
xenocast whoami

키를 에이전트 대화에 붙여 넣지 마세요, 에이전트에게는 키 없이 XenoCI 설정 안내를 읽고 따라 해 줘: https://xenoci.com/agent-setup 한 줄만 건넵니다

xenocast whoami는 키의 조직, 워크스페이스, 권한을 보여 줍니다, 키 값 자체는 어떤 출력에도 나오지 않습니다

키 목록 보기

콘솔 API 키 화면에는 키마다 이름, 워크스페이스, 권한, 생성일, 마지막 사용, 만료, 이번 달 비용이 보입니다, 마지막 사용 시각은 1분 간격으로 갱신됩니다

상태뜻
활성쓸 수 있는 키
만료됨만료 시각이 지난 키, 401 invalid_api_key
폐기됨폐기한 키, 401 invalid_api_key (공개 유출 자동 폐기면 401 api_key_revoked_leaked)

키 폐기하기

  1. API 키에서 키의 작업 → 폐기를 누릅니다
  2. 폐기는 즉시 적용됩니다, 그 뒤의 요청은 401 invalid_api_key입니다
  • 그 키로 시작해 실행 중이거나 기다리는 잡은 15초마다 도는 검사에서 멈춥니다, 상태는 stopped, end_reason은 api_key_revoked(만료면 api_key_expired)이고 멈춘 순간까지 실행한 초만 과금합니다, VM은 바로 정리되고 소유자와 관리자에게 메일이 갑니다
  • 키를 만든 멤버가 조직에서 빠져도 키는 계속 쓸 수 있습니다(워크스페이스 키), 더 쓰지 않을 키는 직접 폐기하세요
  • 폐기한 키는 되살릴 수 없고 목록에서도 지워지지 않습니다(사용량 기록이 키를 가리킵니다)
  • 워크스페이스를 보관하면 그 워크스페이스의 키가 모두 자동으로 폐기됩니다

API로는 API 키 폐기를 씁니다

IP 허용 목록

키를 쓸 수 있는 IP를 CIDR로 정할 수 있습니다, IPv4와 IPv6 모두 되고 목록이 비어 있으면 모든 IP에서 쓸 수 있습니다

범위설정하는 곳누가
조직설정 → 조직 → IP 허용 목록소유자, 관리자
키 하나API 키에서 키의 작업 → IP 허용 목록그 키를 관리할 수 있는 멤버
  • 두 목록이 모두 있으면 두 목록을 모두 통과해야 합니다
  • 목록 밖에서 온 키 요청은 403 ip_not_allowed입니다, error.details.ip에 서버가 본 주소, error.details.list에 막은 목록(organization 또는 api_key)이 들어 있습니다
  • CLI, MCP, GitHub Action, 직접 호출 모두에 적용되고 콘솔 로그인은 막지 않습니다, 목록을 잘못 넣어도 콘솔에서 고칠 수 있습니다
  • 설정 화면에 지금 접속한 IP가 보이고, 그 IP가 빠진 목록을 저장하려 하면 한 번 더 확인합니다
  • GitHub 호스티드 러너처럼 IP가 자주 바뀌는 곳에서 쓰는 키에는 키 단위 목록을 두지 마세요

새 IP에서 처음 쓰였을 때

키가 처음 보는 IP에서 쓰이면 기록하고, 처음 보는 국가면 소유자와 관리자에게 바로 메일을 보냅니다, 같은 국가 안에서 IP만 바뀐 경우는 키마다 하루에 한 번까지만 보냅니다, 키를 처음 쓴 IP는 기준으로만 기록합니다

안전하게 쓰기

  • 키는 CI 시크릿 저장소나 키체인에만 두고 저장소에 커밋하지 마세요, 공개된 곳에서 발견된 키는 자동으로 폐기될 수 있습니다(키 유출 대응)
  • 용도마다 키를 나누세요, 예를 들어 CI용 run 키와 대시보드용 read 키
  • 만료를 두고 주기적으로 새 키로 바꾸세요, 바꿀 때는 새 키를 먼저 넣고 옛 키를 폐기합니다
  • 한 키의 요청이 10분에 1,000건을 넘으면 소유자와 관리자에게 급증 알림 메일이 갑니다

다음 단계