Autenticación

Todos los endpoints de la API de Cotizave (excepto los públicos explícitamente marcados) requieren autenticación mediante API Key.

API Keys

Formato

Las API Keys de Cotizave tienen este formato:

nd-tu-api-key-aqui

Prefijo: nd- identifica la clave dentro del holding Normadata
Payload: cadena base62 que codifica el tipo de clave y bytes aleatorios

Las keys tienen aproximadamente 26 caracteres totales (incluyendo el prefijo).

Cómo autenticarte

Incluye la API Key en el header X-API-Key:

X-API-Key: nd-tu-api-key-aqui

Ejemplos

curl:

curl https://api.cotizave.com/v1/fx/rates \
  -H "X-API-Key: nd-tu-api-key-aqui"

JavaScript:

fetch('https://api.cotizave.com/v1/fx/rates', {
  headers: {
    'X-API-Key': process.env.COTIZAVE_API_KEY
  }
})

Python:

import os
import requests

headers = {
    'X-API-Key': os.environ["COTIZAVE_API_KEY"]
}
response = requests.get('https://api.cotizave.com/v1/fx/rates', headers=headers)

Go:

req, _ := http.NewRequest("GET", "https://api.cotizave.com/v1/fx/rates", nil)
req.Header.Set("X-API-Key", os.Getenv("COTIZAVE_API_KEY"))

Gestión de API Keys

Crear una nueva key

Desde el dashboard (app.cotizave.com → API Keys → “Crear nueva key”):

Asígnale un nombre descriptivo (ej: production-web, ci-tests, local-dev)
La key se muestra una sola vez al momento de crearla. Cópiala y guárdala en un lugar seguro.
Después de cerrar el diálogo, ya no puedes volver a ver la key completa, solo un preview (los últimos 4 caracteres)

Rotar una key

Si sospechas que una key fue comprometida:

Crea una nueva key con el mismo nombre
Actualiza tu aplicación para usar la nueva
Revoca la key vieja desde el dashboard

Rotar claves regularmente (cada 3-6 meses) es una buena práctica de seguridad.

Revocar una key

Desde el dashboard, en la sección API Keys, puedes revocar cualquier key. La revocación es inmediata e irreversible: todos los requests con esa key devolverán 401 Unauthorized a partir de ese momento.

Múltiples keys por Cuenta

Según tu Plan, puedes tener varias keys activas simultáneamente:

Plan	Keys simultáneas
Free	1
Indie	5
Pro	Ilimitadas

Tener varias keys es útil para:

Separar ambientes (producción, staging, desarrollo)
Separar aplicaciones (web, mobile, servicios internos)
Separar equipos o proyectos dentro de la misma organización
Hacer rotación sin downtime

Seguridad

Nunca expongas tus keys

Nunca hagas esto:

Poner la key en código JavaScript frontend (cualquiera puede verla con Dev Tools)
Subir la key a un repositorio público (GitHub escanea y te va a avisar, pero el daño ya puede estar hecho)
Incluir la key en URLs o query strings (quedan en logs del servidor)
Enviar la key en emails, chats o screenshots
Hardcodearla en apps mobile

Haz esto en cambio

Variables de entorno:

# .env
COTIZAVE_API_KEY=nd-tu-api-key-aqui

// En tu código
const key = process.env.COTIZAVE_API_KEY

Secretos en tu proveedor de hosting:

Vercel, Netlify, Render, Railway: panel de Environment Variables
GitHub Actions: Repository Secrets
Otras plataformas de hosting: todas tienen sistemas de secretos equivalentes

Gestor de secretos en producción:

AWS Secrets Manager
Google Secret Manager
HashiCorp Vault
1Password Secrets Automation

Backend vs Frontend

Regla general: las API Keys deben vivir solo en el backend.

Si tu app es frontend puro (React, Vue, Flutter, React Native), deberías:

Crear un endpoint propio en tu backend que consulte Cotizave
Exponer solo los datos procesados al frontend
Nunca incluir la API Key en el código del cliente

Detección de compromiso

Si detectas uso anómalo en tu cuota (muchos más requests de lo esperado), revisa:

El dashboard para ver desde qué IPs vienen los requests
Los logs de tu aplicación
Repositorios públicos donde pueda haberse filtrado

Si confirmas que fue comprometida, revócala inmediatamente y crea una nueva.

Respuestas de autenticación

Request exitoso

Si la API Key es válida, el endpoint responde con los datos solicitados y código 200 OK.

Key inválida o ausente

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": "unauthorized",
  "message": "Missing or invalid API key."
}

Posibles causas:

No incluiste el header X-API-Key
El valor del header está vacío o malformado
La key no existe
La key fue revocada
La key pertenece a otro producto del holding (ej: usaste una key de Normadata en la API de Cotizave)

Key válida pero Plan insuficiente

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "code": "plan_insufficient",
  "message": "This endpoint requires a paid plan. Current plan: free."
}

Algunos endpoints requieren un Plan mínimo. Haz upgrade desde el dashboard para acceder.

Key válida pero cuota agotada

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712614800

{
  "code": "rate_limit_exceeded",
  "message": "Monthly quota exceeded. Upgrade your plan or wait until reset."
}

Ver Rate Limits para más detalles.