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 no parâmetro chain compartilhado. A Robinhood Chain está no ar na Cognivo e tem um endpoint próprio na API, em vez de um valor de chain nos endpoints compartilhados.
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.