Autenticação e chaves de API
O que é uma chave de API
Uma chave de API é o segredo que o seu código envia para a Cognivo para sabermos que uma requisição é sua. Toda chamada à Developer API carrega uma. As chaves ficam dentro de um projeto, e um projeto agrupa as suas chaves e o uso delas.
Leia esta página antes da sua primeira chamada, quando precisar saber o que uma chave tem permissão de fazer, ou quando uma chave puder ter vazado e você precisar desligá-la.
Onde encontrar
Entre no dApp da Cognivo, abra Conta na barra lateral esquerda e depois Developers. Deslogado, a página mostra apenas uma tela de apresentação.
A página Developers tem quatro abas: Chaves, Usage, Endpoints e Início rápido. Tudo o que esta página descreve acontece na aba Chaves.
Acesso live e seu saldo de créditos
Um aviso no topo da página apresenta o modelo de acesso de forma direta: alguns endpoints são gratuitos com qualquer chave ativa, e outros são cobrados por chamada bem-sucedida do seu saldo de créditos Cognivo. Mais abaixo, o card Acesso live à API confirma que uma chave live funciona no momento em que você a cria. Não há etapa de aprovação nem lista de espera.
Ao lado, a página mostra o seu saldo de créditos atual, um botão Adicionar créditos e um botão Acesso enterprise. Enterprise é o único caminho de acesso que passa por uma solicitação, para preços sob medida ou limites maiores. Todo o resto é autoatendimento.
Toda conta Cognivo também recebe 5 créditos grátis por dia, renovados à meia-noite UTC. Veja Billing e créditos para entender como o saldo funciona, e Limites de taxa, erros e cobrança para os preços por endpoint.
A aba Chaves
Escolha um projeto no menu Projeto ou crie um com Novo projeto. A aba Chaves então lista todas as chaves que pertencem a ele.
Cada linha de chave mostra o nome que você deu a ela, se é uma chave de Teste ou Live, o limite por hora que se aplica, as permissões que ela carrega e quando foi criada e usada pela última vez. Último uso: Nunca significa que nenhuma chamada foi feita com aquela chave.
Apenas o prefixo e os quatro últimos caracteres de uma chave são exibidos. A Cognivo não armazena mais nada que possa ser lido de volta, e é por isso que a chave completa aparece exatamente uma vez.
Criando uma chave
Selecione + Nova chave. O formulário pede três coisas: um nome opcional para ajudar você a distinguir as suas chaves, um modo Teste ou Live e pelo menos uma permissão.
Escolher Live mostra o seu saldo de créditos abaixo do seletor de modo, como lembrete de que chamadas live são chamadas reais e são cobradas desse saldo. Escolher Teste cria uma chave de sandbox que nunca é cobrada e tem limites apertados.
Selecione Criar chave e a chave completa aparece uma única vez, em uma caixa de diálogo.
- Use o ícone de cópia para copiar a chave completa enquanto ela ainda está na tela, porque ela não é exibida de novo.
- Selecione Concluído depois de guardar a chave em algum lugar onde você consiga encontrá-la mais tarde.
Se você perder a chave, não é possível recuperá-la. Em vez disso, rotacione a chave, como explicado abaixo.
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 preferem esse formato. Mantenha a chave no seu servidor. Nunca a coloque em código de navegador.
Hoje a API cobre Ethereum, Base e BNB Chain.
Permissões
As chaves negam por padrão. Uma chave só pode chamar os grupos de endpoints que você concedeu no momento da criação. São três permissões, e cada uma libera um conjunto de endpoints.
Intelligence (intel:read) é a permissão do dia a dia. Ela responde "o que está acontecendo com este token ou carteira?": motivos de queda de preço, sinais de risco, comportamento das carteiras do time, PnL realizado e movimentos exatos. Libera POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl e POST /v1/api/wallet/exact-movements.
Security (security:read) permite que uma chave verifique o que uma carteira aprovou, incluindo quais contratos podem gastar os tokens dela e quais permissões são ilimitadas. É somente leitura. Uma chave com essa permissão nunca pode mover fundos nem revogar uma aprovação. Libera POST /v1/api/wallet/approvals.
Liquidity (liquidity:read) permite que uma chave leia o contexto de pools, a custódia de LP e o contexto de locks e queimas. Libera POST /v1/api/intel/liquidity.
GET /v1/api/health não precisa de chave alguma. GET /v1/api/me e GET /v1/api/discover funcionam com qualquer chave válida, quaisquer que sejam as permissões dela.
As permissões são fixadas no momento em que a chave é criada. Para mudá-las, crie uma nova chave com as permissões de que você precisa e revogue a antiga. Uma chamada que falha com 403 scope_denied significa que a chave não carrega a permissão exigida por aquele endpoint.
Chaves de teste e chaves live
| Prefixo | Para que serve | Cobrança | Limite de taxa |
|---|---|---|---|
cogv_test_ | Experimentar a API. Rotulada como Teste e Sandbox no portal. Não consegue executar inteligência live. | nunca cobrada | 25 requisições por hora, 100 por dia, 1 por segundo |
cogv_live_ | Tráfego real. Autoatendimento, funciona imediatamente. | créditos Cognivo por chamada bem-sucedida. Chamadas com falha nunca são cobradas. | 1.000 requisições por hora no início, veja limites de taxa |
Uma chave de teste não é uma chave de produção gratuita. Chamadas live feitas com uma delas respondem 403 sandbox_limited. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.
O portal também mostra um modo de acesso em cada chave. Paid é o pré-pago comum. Trial é uma cota temporária de avaliação com data de término. Partner e Enterprise são acordos combinados com a Cognivo. Suspended significa que a chave não pode executar nada, e o portal mostra o motivo. Um número pequeno de chaves antigas é anterior à cobrança em autoatendimento e só consegue chamar os endpoints de metadados, então chamadas live respondem 403 access_required. Crie uma nova chave live para migrar essas para o pré-pago.
GET /v1/api/me informa o modo de acesso da sua chave, as permissões dela, o seu credits_balance e orientações de recarga. Se o seu saldo não cobrir uma chamada, você recebe 402 payment_required e nada é cobrado. Faça uma recarga e tente de novo.
Rotacionando e revogando
Os dois controles ficam à direita de cada linha de chave.
- Leia os selos Teste e Sandbox ao lado do nome para ver que tipo de chave é esta, junto com o limite por hora exibido ao lado deles.
- Selecione Rotacionar para substituir esta chave por uma nova, que é exibida uma única vez e faz a chave antiga parar de funcionar imediatamente.
- Selecione Revogar para desligar uma chave de vez, por exemplo se ela não for mais necessária ou se você achar que outra pessoa a viu.
Rotacionar pede uma confirmação antes, e a caixa de diálogo diz exatamente o que vai acontecer.
Uma chave rotacionada mantém o nome, as permissões, o nível, qualquer restrição de rede, qualquer data de expiração e qualquer cota restante, então rotacionar é seguro e nunca amplia silenciosamente o que a chave pode fazer. A substituta é exibida uma única vez, na mesma caixa de diálogo de uma chave nova. Revogar é permanente e faz a chave parar de funcionar em todos os endpoints na hora.
Rotacione a qualquer suspeita de vazamento e também em uma rotina periódica.
Restrições que a Cognivo pode aplicar a uma chave
Elas são definidas no registro da chave, e não no formulário do portal, e são aplicadas em toda requisição. Você pode confirmar o que vale para a sua própria chave com GET /v1/api/me.
- Restrição de rede. Uma chave pode ficar limitada a redes específicas. Uma requisição que aponta para outra rede é recusada com
403 chain_denied. A recusa acontece antes de a Cognivo chamar qualquer coisa upstream e antes de qualquer cota ser usada, então uma chamada que a sua chave não tem permissão de fazer nunca custa nada. Informada comoallowed_chains, em quenullsignifica nenhuma restrição. - Expiração. Uma chave pode receber uma data de término. Depois que ela passa, a chave para de funcionar em todos os lugares, incluindo
GET /v1/api/me, e retorna403 key_expired. Informada comoexpires_at, em quenullsignifica que ela não expira. Se uma cota de trial também tiver data de término, vale a que vier primeiro. - Listas de permissão de origem e IP. Uma chave pode ficar limitada a origens específicas, incluindo subdomínios com curinga como
https://*.yourapp.com, ou a endereços IP e faixas CIDR específicos. Requisições vindas de qualquer outro lugar são recusadas com403 origin_denied. Listas vazias significam nenhuma restrição.
Próximos passos
Com uma chave em mãos, faça a sua primeira chamada no Início rápido e depois navegue pela Referência de endpoints para ver o que cada endpoint retorna e quanto custa. Se uma chamada voltar com um código de erro que você não reconhece, Limites de taxa, erros e cobrança lista todos eles.