인증

XenoCI API (https://xenoci.com/api/runner/v1)는 두 가지 자격 증명을 받습니다. API 키는 CLI, MCP 서버, GitHub Actions, 직접 보내는 HTTP 요청에 씁니다. 콘솔 세션(로그인 쿠키)은 콘솔 화면이 쓰고, 결제와 키, 멤버, 워크스페이스 관리처럼 콘솔 전용 엔드포인트는 이것만 받습니다

API 키 형식

키는 xci_live_로 시작하는 59자 문자열입니다

xci_live_<무작위 43자>_<검사 합 6자>

마지막 여섯 자는 앞부분의 검사 합이라 잘못 복사된 키는 서버가 저장소를 보지 않고도 거절합니다. 서버에는 키의 해시만 저장되므로 콘솔에서도 만들 때 한 번만 보이고, 목록에는 앞 12자와 뒤 4자만 남습니다. 키를 만드는 방법은 API 키 받기에 있습니다

요청에 키 보내기

모든 요청의 Authorization 헤더에 Bearer 방식으로 넣습니다

curl https://xenoci.com/api/runner/v1/jobs \
  -H "Authorization: Bearer $XENOCI_API_KEY"

• Authorization 헤더가 있으면 그 값을 키로 봅니다, 쿠키가 같이 와도 키가 틀리면 401입니다
• Bearer 외의 방식이나 다른 헤더 이름은 받지 않습니다
• CLI와 MCP는 XenoCI-Error-Format: 2 헤더도 함께 보내 오류 본문을 최신 형식으로 받습니다, 직접 보낼 때도 붙이는 것을 권합니다

CLI, MCP, 액션은 키를 이렇게 찾습니다

저장한 키는 macOS 키체인, Windows 자격 증명 관리자, Linux secret-service에 두고, 셋 다 없으면 ~/.config/xenoci/credentials.enc (AES-256-GCM 암호화 파일)에 둡니다. XENOCAST_CREDENTIAL_STORE로 저장소를 고를 수 있고 (keychain, wincred, secret-service, file), 서버 주소는 XENOCI_API_URL (기본 https://xenoci.com)로 바꿉니다

xenocast config show

지금 어떤 키가 어디서 읽히는지 보여 줍니다

권한과 범위

키마다 권한과 워크스페이스가 정해져 있습니다

• 키는 만들 때 고른 워크스페이스 하나에서만 잡을 실행하고, 그 키로 쓴 사용량은 그 워크스페이스로 잡힙니다
• 어떤 키도 결제, 키 관리, 멤버와 워크스페이스 관리는 할 수 없습니다, 그 엔드포인트는 403 console_only를 돌려줍니다
• GET /v1/me로 키가 가진 권한과 조직, 워크스페이스를 확인합니다, 응답의 auth는 api_key이고 api_key.permission이 run 또는 read입니다

만료와 폐기

• 만료는 키를 만들 때 만료 없음, 30일, 90일, 1년 가운데 고릅니다
• 만료되거나 폐기된 키, 보관된 워크스페이스의 키는 모두 401 invalid_api_key로 거절됩니다
• 폐기는 즉시 적용되지만 이미 시작한 잡은 끝까지 실행됩니다
• 공개 저장소에서 발견되어 자동 폐기된 키는 401 api_key_revoked_leaked를 받습니다, 새 키를 만들어 바꿔 넣으세요

인증 오류

오류 본문은 아래 모양이고 docs_url은 이 문서의 오류 코드 페이지로 연결됩니다. 모든 응답에는 X-Request-Id 헤더가 붙습니다

{
  "error": {
    "code": "invalid_api_key",
    "message": "Unknown, revoked, expired or checksum-invalid key",
    "retryable": false,
    "fault": "client",
    "request_id": "req_...",
    "docs_url": "https://xenoci.com/docs/errors#invalid_api_key"
  }
}

다음 단계