본문으로 건너뛰기

인증 및 API 키

키 보내기​

표준 헤더는 X-API-Key입니다:

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'

이를 선호하는 클라이언트 라이브러리를 위해 Authorization: Bearer YOUR_API_KEY도 별칭으로 허용됩니다.

키 저장 방식​

Cognivo는 전체 키를 절대 저장하지 않습니다. 단방향 해시와 접두사, 마지막 네 글자만 보관되며, 그래서 전체 키는 생성 시 딱 한 번만 표시될 수 있습니다. 비밀번호처럼 다루세요.

샌드박스 키 vs 라이브 키​

접두사용도과금속도 상한
cogv_test_샌드박스: 라이브 체인 데이터에서의 통합 테스트과금 없음. 관리자가 활성화한 경우에만 소량의 라이브 데모 허용량을 실행할 수 있음시간당 25 요청, 일 100 요청 하드캡
cogv_live_프로덕션유료 사용은 성공한 호출당 Cognivo 크레딧으로 과금되며, 실패한 호출에는 과금되지 않음여러분의 접근 모드 제한

두 환경 모두 동일한 라이브 체인 데이터와 동일한 엔드포인트에 접근합니다. 차이는 속도 상한과 접근 모드입니다. 샌드박스 키로 개발하고 라이브 키로 배포하세요.

접근 모드, 쉽게 정리하면​

  • 무료 키 - 탐색 전용: 문서, GET /v1/api/health, GET /v1/api/me, 제한적인 샌드박스/데모 호출. 실행형 인텔리전스 엔드포인트는 무료로 실행되는 대신 403 access_required 같은 명확한 오류로 응답합니다.
  • 트라이얼 - 관리자가 부여하며, 제한적이고 만료됩니다. 라이브 인텔리전스 엔드포인트를 평가해 볼 수 있습니다.
  • 유료 - 성공한 호출당 Cognivo 크레딧을 공개된 엔드포인트별 비용에 따라 차감합니다. 실패한 호출에는 과금되지 않습니다.
  • 파트너 / 엔터프라이즈 - 맞춤 요금, 더 높은 한도, 엔드포인트별 접근. Developer 포털에서 접근을 요청하세요.

스코프 (권한)​

키는 **기본 거부(default-deny)**입니다. 키는 생성 시 부여한 엔드포인트 그룹만 호출할 수 있습니다. 스코프는 세 가지이며, 각각은 단순히 엔드포인트 묶음 하나를 열어 줍니다.

intel:read - 토큰 및 지갑 인텔리전스​

일상적으로 쓰는 스코프입니다. "이 토큰이나 지갑에 무슨 일이 벌어지고 있는가?"를 키로 물어볼 수 있게 해 줍니다: 가격 하락 요인, 리스크 신호, 팀 지갑 행동, 실현 손익, 정확한 자금 이동.

열리는 엔드포인트: POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl, POST /v1/api/wallet/exact-movements

security:read - 지갑 안전 스캔​

지갑이 무엇을 승인했는지 확인할 수 있게 해 줍니다: 어떤 컨트랙트가 그 지갑의 토큰을 사용할 수 있는지 확인하고 무제한 허용량(allowance)에 플래그를 답니다. 읽기 전용입니다. 이 스코프를 가진 키는 절대 자금을 옮기거나 무언가를 철회할 수 없습니다.

열리는 엔드포인트: POST /v1/api/wallet/approvals

liquidity:read - 유동성 및 LP 읽기​

토큰의 유동성이 진짜인지, LP 토큰이 어디에 있는지 확인할 수 있게 해 줍니다: 풀 상황, LP 보관(custody), 잠금 및 소각 현황.

열리는 엔드포인트: POST /v1/api/intel/liquidity

GET /v1/api/health는 키가 전혀 필요 없고, GET /v1/api/me와 GET /v1/api/discover는 스코프와 무관하게 어떤 유효한 키로도 동작합니다.

키의 스코프는 포털에서 언제든 수정할 수 있습니다. 호출이 403 scope_denied로 실패한다면, 해당 엔드포인트에 필요한 스코프를 그 키가 갖고 있지 않은 것뿐입니다.

로테이션과 폐기​

  • 폐기(Revoke) 는 키를 죽입니다. 1분 이내에 인증이 중단됩니다.
  • 로테이션(Rotate) 은 같은 이름, 스코프, 티어를 가진 대체 키를 만들어 한 번만 보여 주고, 같은 단계에서 이전 키를 폐기합니다. 유출이 의심될 때와 정기적인 일정으로 사용하세요.

선택적 제한​

키별로 추가 허용 목록을 설정할 수 있습니다:

  • 오리진 (정확한 오리진 또는 https://*.yourapp.com 같은 와일드카드 서브도메인) - 다른 Origin을 제시하는 요청은 거부됩니다.
  • IP / CIDR 범위 - 다른 주소에서 오는 요청은 거부됩니다.

목록이 비어 있으면 제한이 없다는 뜻입니다.

키는 어디서 오나요​

키는 기존 Cognivo 계정을 사용해 셀프서비스 Developer 포털에서만 생성됩니다. 신규 연동을 위한 수동/레거시 키 발급은 없습니다.