인증

XenoCI API (https://xenoci.com/api/runner/v1)는 요청을 인증하는 두 가지 방법을 지원합니다

두 방법은 서로 넘어가지 않습니다, API 키로는 콘솔 전용 엔드포인트를 부를 수 없고(403 console_only), 콘솔 세션은 사람이 브라우저에서만 씁니다, 빌드를 자동화하려면 API 키를 쓰세요

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로 거절됩니다
• 폐기는 즉시 적용됩니다, 그 키로 시작한 실행 중인 잡도 서버의 주기 점검(15초에서 30초)에서 멈추고 VM이 지워집니다 (주기 점검은 서버에 적용하는 중입니다)
• 공개 저장소에서 발견되어 자동 폐기된 키는 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"
  }
}

다음 단계