Aller au contenu principal

Authentification et clés d'API

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.

Comment les clés sont stockées​

Cognivo ne stocke jamais votre clé complète. Seuls un hachage à sens unique, le préfixe et les quatre derniers caractères sont conservés, ce qui explique pourquoi la clé complète ne peut être affichée qu'une seule fois à la création. Traitez-la comme un mot de passe.

Clés sandbox vs clés live​

PréfixeUsageFacturationPlafond de débit
cogv_test_sandbox : tests d'intégration sur des données de chaîne en directnon facturée ; ne peut exécuter qu'une petite allocation de démo en direct quand un administrateur l'activeplafond strict de 25 requêtes/heure et 100/jour
cogv_live_productionl'usage payant est facturé en crédits Cognivo par appel réussi ; les appels échoués ne sont pas facturésvotre limite selon le mode d'accès

Les deux environnements atteignent les mêmes endpoints sur des données de chaîne en direct ; les différences sont le plafond de débit et le mode d'accès. Développez avec une clé sandbox, déployez avec une clé live.

Les modes d'accès, en clair​

  • Clé gratuite - exploration uniquement : la documentation, GET /v1/api/health, GET /v1/api/me et des appels sandbox/démo limités. Les endpoints d'intelligence exécutables répondent par une erreur claire comme 403 access_required au lieu de s'exécuter gratuitement.
  • Trial - accordé par un administrateur, limité et à durée déterminée ; il vous permet d'évaluer les endpoints d'intelligence en direct.
  • Payant - des crédits Cognivo par appel réussi, aux coûts par endpoint publiés ; les appels échoués ne sont pas facturés.
  • Partenaire / Enterprise - tarifs sur mesure, limites plus élevées et accès spécifique par endpoint ; demandez l'accès depuis le portail développeur.

Scopes (permissions)​

Les clés fonctionnent en refus par défaut : une clé ne peut appeler que les groupes d'endpoints que vous lui avez accordés à la création. Il existe trois scopes, et chacun débloque simplement un ensemble d'endpoints.

intel:read - intelligence de tokens et de wallets​

Le scope du quotidien. Il permet à votre clé de demander "que se passe-t-il avec ce token ou ce wallet ?" : causes de baisse de prix, signaux de risque, comportement des wallets d'équipe, PnL réalisé et mouvements exacts.

Débloque : 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 - analyses de sécurité de wallets​

Permet à votre clé de vérifier ce qu'un wallet a approuvé : quels contrats peuvent dépenser ses tokens, en signalant les autorisations illimitées. Lecture seule ; une clé avec ce scope ne peut jamais déplacer de fonds ni révoquer quoi que ce soit.

Débloque : POST /v1/api/wallet/approvals

liquidity:read - lectures de liquidité et de LP​

Permet à votre clé de vérifier si la liquidité d'un token est réelle et où se trouvent les tokens LP : contexte du pool, garde des LP, contexte de verrouillage et de burn.

Débloque : POST /v1/api/intel/liquidity

GET /v1/api/health ne nécessite aucune clé, et GET /v1/api/me et GET /v1/api/discover fonctionnent avec n'importe quelle clé valide, quels que soient ses scopes.

Vous pouvez modifier les scopes d'une clé à tout moment dans le portail. Si un appel échoue avec 403 scope_denied, la clé ne porte simplement pas le scope dont cet endpoint a besoin.

Rotation et révocation​

  • Révoquer tue une clé. Elle cesse de s'authentifier en moins d'une minute.
  • Effectuer une rotation crée une clé de remplacement avec le même nom, les mêmes scopes et le même palier, l'affiche une fois, et révoque l'ancienne clé dans la même opération. Utilisez-la à la moindre suspicion de fuite et selon un calendrier régulier.

Restrictions optionnelles​

Pour chaque clé, vous pouvez en plus définir des listes d'autorisation :

  • Origines (origines exactes ou sous-domaines avec joker comme https://*.yourapp.com) - les requêtes présentant un autre Origin sont rejetées.
  • IPs / plages CIDR - les requêtes provenant d'autres adresses sont rejetées.

Des listes vides signifient aucune restriction.

D'où viennent les clés​

Les clés sont créées uniquement dans le portail développeur en libre-service, avec votre compte Cognivo existant. Il n'y a pas d'émission de clés manuelle/héritée pour les nouvelles intégrations.