Autenticación y claves de API

Qué es una clave de API

Una clave de API es el secreto que tu código envía a Cognivo para que sepamos que una solicitud es tuya. Cada llamada a la Developer API lleva una. Las claves viven dentro de un proyecto, y un proyecto agrupa tus claves y su uso.

Lee esta página antes de tu primera llamada, cuando necesites saber qué puede hacer una clave, o cuando una clave pueda haberse filtrado y necesites desactivarla.

Dónde encontrarlo

Inicia sesión en la dApp de Cognivo, abre Account en la barra lateral izquierda y luego Developers. Sin sesión iniciada, la página muestra solo una pantalla de orientación.

La página de Developers tiene cuatro pestañas: Keys, Usage, Endpoints y Quickstart. Todo lo de esta página ocurre en la pestaña Keys.

Acceso live y tu saldo de créditos

Un banner en la parte superior de la página expone el modelo de acceso con claridad: algunos endpoints son gratis con cualquier clave activa, y otros se cobran por llamada exitosa desde tu saldo de créditos de Cognivo. Más abajo, la tarjeta Live API access confirma que una clave live funciona desde el momento en que la creas. No hay paso de aprobación ni lista de espera.

Al lado, la página muestra tu saldo de créditos actual, un botón Top up credits y un botón Enterprise access. Enterprise es la única vía de acceso que pasa por una solicitud, para precios a medida o límites más altos. Todo lo demás es de autoservicio.

El panel de acceso a la API live, más abajo en la página Developers.Ampliar imagen

Cada cuenta de Cognivo recibe además 5 créditos gratis al día, que se reinician a medianoche UTC. Consulta Facturación y créditos para ver cómo funciona el saldo, y Límites de tasa, errores y facturación para los precios por endpoint.

La pestaña Keys

Elige un proyecto en el desplegable Project, o crea uno con New project. La pestaña Keys lista entonces todas las claves que le pertenecen.

La pestaña Keys en la página Developers, que lista todas las claves del proyecto seleccionado.Ampliar imagen

Cada fila de clave muestra el nombre que le diste, si es una clave Test o Live, el límite por hora que aplica, los permisos que lleva, y cuándo se creó y se usó por última vez. Last used: Never significa que nunca se ha hecho una llamada con esa clave.

Solo se muestran el prefijo y los últimos cuatro caracteres de una clave. Cognivo no guarda nada más que pueda volver a leerse, y por eso la clave completa aparece exactamente una vez.

Crear una clave

Selecciona + New key. El formulario pide tres cosas: un nombre opcional para ayudarte a distinguir tus claves, un modo Test o Live, y al menos un permiso.

El formulario de clave nueva en la página Developers, que se abre con el botón Clave nueva.Ampliar imagen

Elegir Live muestra tu saldo de créditos bajo el desplegable de modo, como recordatorio de que las llamadas live son llamadas reales y se cobran de ese saldo. Elegir Test crea una clave de sandbox que nunca se cobra y tiene límites estrictos.

Selecciona Create key y la clave completa aparece una sola vez, en un diálogo.

1. Usa el icono de copiar para copiar la clave completa mientras sigue en pantalla, porque no se vuelve a mostrar.
2. Selecciona Listo cuando hayas guardado la clave en un lugar donde puedas encontrarla más adelante.

El diálogo de clave de una sola vez en la pestaña Keys, que aparece justo al crear una clave nueva.Ampliar imagen

Si pierdes la clave, no puedes recuperarla. En su lugar, rota la clave, algo que se explica más abajo.

Enviar tu clave

El encabezado canónico es 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 se acepta como alias para las librerías cliente que lo prefieren. Mantén la clave en tu servidor. Nunca la pongas en código de navegador.

Hoy la API cubre Ethereum, Base y BNB Chain.

Permisos

Las claves deniegan por defecto. Una clave solo puede llamar a los grupos de endpoints que concediste al crearla. Hay tres permisos, y cada uno desbloquea un conjunto de endpoints.

Intelligence (intel:read) es el permiso del día a día. Responde a "¿qué está pasando con este token o billetera?": causas de caídas de precio, señales de riesgo, comportamiento de las billeteras del equipo, PnL realizado y movimientos exactos. Desbloquea POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl y POST /v1/api/wallet/exact-movements.

Security (security:read) permite que una clave revise qué ha aprobado una billetera, incluidos qué contratos pueden gastar sus tokens y qué autorizaciones son ilimitadas. Es de solo lectura. Una clave con este permiso nunca puede mover fondos ni revocar una aprobación. Desbloquea POST /v1/api/wallet/approvals.

Liquidity (liquidity:read) permite que una clave lea el contexto de los pools, la custodia de LP y el contexto de locks y quemas. Desbloquea POST /v1/api/intel/liquidity.

GET /v1/api/health no necesita clave alguna. GET /v1/api/me y GET /v1/api/discover funcionan con cualquier clave válida, sean cuales sean sus permisos.

Los permisos se fijan al crear la clave. Para cambiarlos, crea una clave nueva con los permisos que necesitas y revoca la antigua. Una llamada que falla con 403 scope_denied significa que la clave no lleva el permiso que ese endpoint necesita.

Claves de prueba y claves live

Prefijo	Para qué sirve	Facturación	Tope de tasa
cogv_test_	Probar la API. Etiquetada como Test y Sandbox en el portal. No puede ejecutar inteligencia en vivo.	nunca se cobra	25 solicitudes por hora, 100 por día, 1 por segundo
cogv_live_	Tráfico real. De autoservicio, funciona de inmediato.	créditos de Cognivo por llamada exitosa. Las llamadas fallidas nunca se cobran.	1,000 solicitudes por hora para empezar, ver límites de tasa

Una clave de prueba no es una clave de producción gratuita. Las llamadas live hechas con una responden 403 sandbox_limited. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

El portal muestra además un modo de acceso en cada clave. Paid es el pago por uso ordinario. Trial es una asignación de evaluación temporal con fecha de fin. Partner y Enterprise son acuerdos establecidos con Cognivo. Suspended significa que la clave no puede ejecutar nada, y el portal muestra el motivo. Un número reducido de claves antiguas es anterior a la facturación de autoservicio y solo puede llamar a los endpoints de metadatos, así que las llamadas live responden 403 access_required. Crea una clave live nueva para pasar esas al pago por uso.

GET /v1/api/me informa del modo de acceso de tu clave, sus permisos, tu credits_balance y orientación para recargar. Si tu saldo no puede cubrir una llamada, obtienes 402 payment_required y no se cobra nada. Recarga y reintenta.

Rotar y revocar

Ambos controles están a la derecha de cada fila de clave.

1. Fíjate en las insignias Test y Sandbox junto al nombre para saber qué tipo de clave es, y en el límite por hora que aparece al lado.
2. Selecciona Rotar para sustituir esta clave por una nueva, que se muestra una sola vez y hace que la clave antigua deje de funcionar de inmediato.
3. Selecciona Revocar para desactivar una clave de forma definitiva, por ejemplo si ya no la necesitas o crees que alguien más la ha visto.

Las filas de claves en la pestaña Keys de la página Developers.Ampliar imagen

Rotar te pide confirmar primero, y el diálogo dice exactamente qué va a pasar.

La confirmación de rotación en la pestaña Keys, que aparece después de seleccionar Rotar en una clave.Ampliar imagen

Una clave rotada conserva su nombre, sus permisos, su nivel, cualquier restricción de red, cualquier fecha de expiración y cualquier asignación restante, así que rotar es seguro y nunca amplía en silencio lo que la clave puede hacer. El reemplazo se muestra una vez, en el mismo diálogo que una clave nueva. Revocar es permanente y detiene el funcionamiento de la clave en todos los endpoints de inmediato.

Rota ante cualquier sospecha de filtración, y de forma periódica.

Restricciones que Cognivo puede aplicar a una clave

Estas se configuran en el registro de la clave y no en el formulario del portal, y se aplican en cada solicitud. Puedes confirmar qué aplica a tu propia clave con GET /v1/api/me.

• Restricción de red. Una clave puede limitarse a redes específicas. Una solicitud que nombra otra red se rechaza con 403 chain_denied. El rechazo ocurre antes de que Cognivo llame a nada aguas arriba y antes de usar ninguna asignación, así que una llamada que tu clave no tiene permitido hacer nunca te cuesta nada. Se informa como allowed_chains, donde null significa sin restricción.
• Expiración. A una clave se le puede dar una fecha de fin. Una vez pasada, la clave deja de funcionar en todas partes, incluido GET /v1/api/me, y devuelve 403 key_expired. Se informa como expires_at, donde null significa que no expira. Si una asignación trial también tiene fecha de fin, aplica la que llegue primero.
• Listas de permitidos de Origin e IP. Una clave puede limitarse a orígenes específicos, incluidos subdominios con comodín como https://*.yourapp.com, o a direcciones IP y rangos CIDR específicos. Las solicitudes desde cualquier otro lugar se rechazan con 403 origin_denied. Las listas vacías significan sin restricción.

Siguientes pasos

Con una clave en la mano, haz tu primera llamada en el Inicio rápido, y luego explora la Referencia de endpoints para ver qué devuelve cada endpoint y cuánto cuesta. Si una llamada devuelve un código de error que no reconoces, Límites de tasa, errores y facturación los lista todos.