Authentification et clés d'API
Ce qu'est une clé d'API
Une clé d'API est le secret que votre code envoie à Cognivo pour que nous sachions qu'une requête est bien la vôtre. Chaque appel à la Developer API en porte une. Les clés vivent à l'intérieur d'un projet, et un projet regroupe vos clés et leur usage.
Lisez cette page avant votre premier appel, quand vous avez besoin de savoir ce qu'une clé a le droit de faire, ou quand une clé a pu fuiter et que vous devez la désactiver.
Où la trouver
Connectez-vous à la dApp Cognivo, ouvrez Account dans la barre latérale gauche, puis Developers. Non connecté, la page n'affiche qu'un écran de présentation.
La page Developers comporte quatre onglets : Keys, Usage, Endpoints et Quickstart. Tout ce qui figure sur cette page se déroule dans l'onglet Keys.
L'accès en direct et votre solde de crédits
Une bannière en haut de la page énonce clairement le modèle d'accès : certains endpoints sont gratuits avec n'importe quelle clé active, et d'autres sont facturés par appel réussi sur votre solde de crédits Cognivo. Plus bas, la carte Live API access confirme qu'une clé en direct fonctionne dès sa création. Il n'y a ni étape d'approbation ni liste d'attente.
À côté, la page affiche votre solde de crédits actuel, un bouton Top up credits et un bouton Enterprise access. Enterprise est le seul chemin d'accès qui passe par une demande, pour des tarifs sur mesure ou des limites plus élevées. Tout le reste est en libre-service.
Chaque compte Cognivo reçoit également 5 crédits gratuits par jour, réinitialisés à minuit UTC. Voir Facturation et crédits pour le fonctionnement du solde, et Limites de débit, erreurs et facturation pour les prix par endpoint.
L'onglet Keys
Choisissez un projet dans le menu déroulant Project, ou créez-en un avec New project. L'onglet Keys liste ensuite toutes les clés qui lui appartiennent.
Chaque ligne de clé affiche le nom que vous lui avez donné, s'il s'agit d'une clé Test ou Live, la limite horaire qui s'applique, les permissions qu'elle porte, ainsi que sa date de création et de dernière utilisation. Last used: Never signifie qu'aucun appel n'a jamais été effectué avec cette clé.
Seuls le préfixe et les quatre derniers caractères d'une clé sont affichés. Cognivo ne stocke rien d'autre qui puisse être relu, ce qui explique pourquoi la clé complète n'apparaît qu'une seule fois.
Créer une clé
Sélectionnez + New key. Le formulaire demande trois choses : un nom facultatif pour vous aider à distinguer vos clés, un mode Test ou Live, et au moins une permission.
Choisir Live affiche votre solde de crédits sous le menu déroulant du mode, pour rappeler que les appels en direct sont de vrais appels et qu'ils sont facturés sur ce solde. Choisir Test crée une clé sandbox qui n'est jamais facturée et dont les limites sont strictes.
Sélectionnez Create key et la clé complète apparaît une seule fois, dans une boîte de dialogue.
- Utilisez l'icône de copie pour copier la clé complète tant qu'elle est à l'écran, car elle n'est plus affichée ensuite.
- Sélectionnez Terminé une fois la clé rangée dans un endroit où vous pourrez la retrouver plus tard.
Si vous perdez la clé, vous ne pouvez pas la récupérer. Faites plutôt tourner la clé, ce qui est expliqué plus bas.
Envoyer votre clé
L'en-tête canonique est 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 est accepté comme alias pour les bibliothèques clientes qui le préfèrent. Gardez la clé sur votre serveur. Ne la mettez jamais dans du code de navigateur.
L'API couvre aujourd'hui Ethereum, Base et BNB Chain dans le paramètre chain partagé. Robinhood Chain est en service dans Cognivo et dispose de son propre endpoint sur l'API, plutôt que d'une valeur de chain sur les endpoints partagés.
Permissions
Les clés refusent par défaut. Une clé ne peut appeler que les groupes d'endpoints que vous avez accordés lors de sa création. Il existe trois permissions, et chacune débloque un ensemble d'endpoints.
Intelligence (intel:read) est la permission du quotidien. Elle répond à « que se passe-t-il avec ce token ou ce wallet ? » : facteurs de baisse de prix, signaux de risque, comportement des wallets d'équipe, PnL réalisé et mouvements exacts. Elle débloque POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl et POST /v1/api/wallet/exact-movements.
Security (security:read) permet à une clé de vérifier ce qu'un wallet a approuvé, y compris quels contrats peuvent dépenser ses tokens et quelles autorisations sont illimitées. Elle est en lecture seule. Une clé dotée de cette permission ne peut jamais déplacer de fonds ni révoquer une approbation. Elle débloque POST /v1/api/wallet/approvals.
Liquidity (liquidity:read) permet à une clé de lire le contexte des pools, la garde des LP, ainsi que le contexte de verrouillage et de burn. Elle débloque POST /v1/api/intel/liquidity.
GET /v1/api/health ne nécessite aucune clé. GET /v1/api/me et GET /v1/api/discover fonctionnent avec n'importe quelle clé valide, quelles que soient ses permissions.
Les permissions sont figées à la création de la clé. Pour les changer, créez une nouvelle clé avec les permissions dont vous avez besoin et révoquez l'ancienne. Un appel qui échoue avec 403 scope_denied signifie que la clé ne porte pas la permission dont cet endpoint a besoin.
Clés de test et clés en direct
| Préfixe | À quoi elle sert | Facturation | Plafond de débit |
|---|---|---|---|
cogv_test_ | Essayer l'API. Étiquetée Test et Sandbox dans le portail. Ne peut pas exécuter d'intelligence en direct. | jamais facturée | 25 requêtes par heure, 100 par jour, 1 par seconde |
cogv_live_ | Trafic réel. En libre-service, fonctionne immédiatement. | Crédits Cognivo par appel réussi. Les appels en échec ne sont jamais facturés. | 1 000 requêtes par heure au départ, voir limites de débit |
Une clé de test n'est pas une clé de production gratuite. Les appels en direct effectués avec une telle clé répondent 403 sandbox_limited. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.
Le portail affiche aussi un mode d'accès sur chaque clé. Paid correspond au paiement à l'usage ordinaire. Trial est une allocation d'évaluation temporaire avec une date de fin. Partner et Enterprise sont des accords conclus avec Cognivo. Suspended signifie que la clé ne peut rien exécuter, et le portail en affiche la raison. Un petit nombre de clés plus anciennes sont antérieures à la facturation en libre-service et ne peuvent appeler que les endpoints de métadonnées, si bien que les appels en direct répondent 403 access_required. Créez une nouvelle clé en direct pour les basculer vers le paiement à l'usage.
GET /v1/api/me indique le mode d'accès de votre clé, ses permissions, votre credits_balance et des conseils de rechargement. Si votre solde ne peut pas couvrir un appel, vous obtenez 402 payment_required et rien n'est facturé. Rechargez et réessayez.
Rotation et révocation
Les deux commandes se trouvent à droite de chaque ligne de clé.
- Regardez les badges Test et Sandbox à côté du nom pour savoir de quel type de clé il s'agit, ainsi que la limite horaire affichée juste à côté.
- Sélectionnez Rotation pour remplacer cette clé par une nouvelle, qui est affichée une seule fois et qui rend l'ancienne clé inutilisable immédiatement.
- Sélectionnez Révoquer pour désactiver définitivement une clé, par exemple si elle ne sert plus ou si vous pensez que quelqu'un d'autre l'a vue.
La rotation vous demande d'abord de confirmer, et la boîte de dialogue indique exactement ce qui va se passer.
Une clé dont on a fait la rotation conserve son nom, ses permissions, son palier, toute restriction de réseau, toute date d'expiration et toute allocation restante, si bien que la rotation est sans danger et n'élargit jamais discrètement ce que la clé peut faire. La clé de remplacement est affichée une seule fois, dans la même boîte de dialogue que pour une nouvelle clé. La révocation est définitive et empêche immédiatement la clé de fonctionner sur tous les endpoints.
Faites une rotation à la moindre suspicion de fuite, et de façon régulière.
Restrictions que Cognivo peut appliquer à une clé
Elles sont définies sur l'enregistrement de la clé plutôt que dans le formulaire du portail, et elles sont appliquées à chaque requête. Vous pouvez vérifier ce qui s'applique à votre propre clé avec GET /v1/api/me.
- Restriction de réseau. Une clé peut être limitée à certains réseaux. Une requête nommant un autre réseau est refusée avec
403 chain_denied. Le refus intervient avant que Cognivo n'appelle quoi que ce soit en amont et avant qu'aucune allocation ne soit utilisée, si bien qu'un appel que votre clé n'est pas autorisée à faire ne vous coûte jamais rien. Rapporté sousallowed_chains, oùnullsignifie aucune restriction. - Expiration. Une clé peut recevoir une date de fin. Une fois passée, la clé cesse de fonctionner partout, y compris pour
GET /v1/api/me, et renvoie403 key_expired. Rapporté sousexpires_at, oùnullsignifie qu'elle n'expire pas. Si une allocation d'essai a également une date de fin, c'est la première échéance qui s'applique. - Listes d'autorisation d'origines et d'IP. Une clé peut être limitée à certaines origines, y compris des sous-domaines génériques comme
https://*.yourapp.com, ou à certaines adresses IP et plages CIDR. Les requêtes provenant d'ailleurs sont refusées avec403 origin_denied. Des listes vides signifient aucune restriction.
Étapes suivantes
Une fois la clé en main, effectuez votre premier appel avec le Démarrage rapide, puis parcourez la Référence des endpoints pour voir ce que chaque endpoint renvoie et ce qu'il coûte. Si un appel revient avec un code d'erreur que vous ne reconnaissez pas, Limites de débit, erreurs et facturation les liste tous.