Pular para o conteúdo principal

Autenticação e chaves de API

Enviando sua chave​

O cabeçalho canônico é 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 é aceito como alias para bibliotecas cliente que o prefiram.

Como as chaves são armazenadas​

A Cognivo nunca armazena a sua chave completa. Apenas um hash unidirecional, o prefixo e os últimos quatro caracteres são mantidos, e é por isso que a chave completa pode ser exibida exatamente uma vez na criação. Trate-a como uma senha.

Chaves sandbox vs chaves live​

PrefixoFinalidadeCobrançaTeto de taxa
cogv_test_sandbox: testes de integração com dados de chain ao vivonão é cobrada; só consegue executar uma pequena cota de demo ao vivo quando um administrador a habilitateto fixo de 25 requisições/hora e 100/dia
cogv_live_produçãoo uso pago é cobrado em créditos Cognivo por chamada bem-sucedida; chamadas com falha não são cobradasseu limite por modo de acesso

Os dois ambientes acessam os mesmos endpoints com dados de chain ao vivo; as diferenças são o teto de taxa e o modo de acesso. Desenvolva com uma chave sandbox, publique com uma chave live.

Modos de acesso, sem rodeios​

  • Chave gratuita - apenas exploração: a documentação, GET /v1/api/health, GET /v1/api/me e chamadas limitadas de sandbox/demo. Os endpoints de inteligência executáveis respondem com um erro claro como 403 access_required em vez de executar de graça.
  • Trial - concedido por um administrador, limitado e com prazo de expiração; permite avaliar os endpoints de inteligência ao vivo.
  • Pago - créditos Cognivo por chamada bem-sucedida, aos custos por endpoint publicados; chamadas com falha não são cobradas.
  • Partner / Enterprise - preços sob medida, limites maiores e acesso específico por endpoint; solicite acesso pelo portal do desenvolvedor.

Escopos (permissões)​

As chaves são de negação por padrão: uma chave só pode chamar os grupos de endpoints que você concedeu ao criá-la. Existem três escopos, e cada um simplesmente desbloqueia um conjunto de endpoints.

intel:read - inteligência de tokens e carteiras​

O escopo do dia a dia. Ele permite que a sua chave pergunte "o que está acontecendo com este token ou carteira?": causas de queda de preço, sinais de risco, comportamento das carteiras do time, PnL realizado e movimentos exatos.

Desbloqueia: 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 - varreduras de segurança de carteiras​

Permite que a sua chave verifique o que uma carteira aprovou: quais contratos podem gastar os tokens dela, sinalizando allowances ilimitadas. Somente leitura; uma chave com este escopo nunca pode mover fundos nem revogar nada.

Desbloqueia: POST /v1/api/wallet/approvals

liquidity:read - leituras de liquidez e LP​

Permite que a sua chave verifique se a liquidez de um token é real e onde estão os tokens de LP: contexto do pool, custódia do LP, contexto de locks e queimas.

Desbloqueia: POST /v1/api/intel/liquidity

GET /v1/api/health não precisa de chave alguma, e GET /v1/api/me e GET /v1/api/discover funcionam com qualquer chave válida, sejam quais forem os escopos dela.

Você pode editar os escopos de uma chave a qualquer momento no portal. Se uma chamada falhar com 403 scope_denied, a chave simplesmente não carrega o escopo de que aquele endpoint precisa.

Rotação e revogação​

  • Revogar mata uma chave. Ela para de autenticar em menos de um minuto.
  • Rotacionar cria uma chave substituta com o mesmo nome, escopos e tier, exibe-a uma vez e revoga a chave antiga na mesma etapa. Use em qualquer suspeita de vazamento e em uma rotina regular.

Restrições opcionais​

Por chave, você pode adicionalmente criar listas de permissão:

  • Origens (origens exatas ou subdomínios com curinga como https://*.yourapp.com) - requisições que apresentem um Origin diferente são rejeitadas.
  • IPs / faixas CIDR - requisições de outros endereços são rejeitadas.

Listas vazias significam sem restrição.

De onde vêm as chaves​

As chaves são criadas apenas no portal do desenvolvedor self-service, usando a sua conta Cognivo existente. Não há emissão manual/legada de chaves para novas integrações.