← Volver a docs
🔑 API / Autenticación

Autenticación por API Key

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

API Keys

Formato

Las API Keys de Cotizave tienen este formato:

ejemplo
ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d
  • Prefijo: ctz_live_ identifica una clave de Cotizave. Los 38 caracteres del cuerpo son base62 (24 bytes random + 4 bytes de checksum CRC32) que permite detectar typos sin tocar la base de datos.

Cómo autenticarte

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

header
X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d

Ejemplos

curl https://api.cotizave.com/v1/fx/rates \
  -H "X-API-Key: ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d"
fetch('https://api.cotizave.com/v1/fx/rates', {
  headers: { 'X-API-Key': process.env.COTIZAVE_API_KEY }
})
import os, requests
headers = {'X-API-Key': os.environ["COTIZAVE_API_KEY"]}
response = requests.get('https://api.cotizave.com/v1/fx/rates', headers=headers)
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"):

  1. La key se muestra una sola vez al momento de crearla. Cópiala y guárdala en un lugar seguro.
  2. 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

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

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

Revocar una 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

PlanKeys simultáneas
Free1
Pro5
BusinessNegociado

Útil para separar ambientes (producción, staging, desarrollo), separar aplicaciones, equipos o hacer rotación sin downtime.

Seguridad

Nunca expongas tus keys

!

Nunca hagas esto: poner la key en código JavaScript frontend · subirla a un repositorio público · incluirla en URLs o query strings · enviarla por email, chat o screenshots · hardcodearla en apps mobile.

Haz esto en cambio

.env
COTIZAVE_API_KEY=ctz_live_aB3cD8fG2hJ5kL9mN1pQ4rS7tU0vWxYzA6bC3d
en tu código
const key = process.env.COTIZAVE_API_KEY
★

Regla general: las API Keys deben vivir solo en el backend. Si tu app es frontend puro, crea un endpoint propio en tu backend que consulte Cotizave y nunca incluyas la API Key en el código del cliente.

Respuestas de autenticación

Key inválida o ausente

401 Unauthorized
HTTP/1.1 401 Unauthorized

{
  "code": "invalid_api_key",
  "message": "API key is missing, invalid, or revoked."
}

Key revocada

401 Unauthorized
HTTP/1.1 401 Unauthorized

{
  "code": "key_revoked",
  "message": "API key has been revoked."
}

Cuenta suspendida

403 Forbidden
HTTP/1.1 403 Forbidden

{
  "code": "account_inactive",
  "message": "Account is suspended or banned."
}

Key válida pero cuota agotada

429 Too Many Requests
HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded."
}

Ver Rate Limits para más detalles.

Próximos pasos

← AnteriorInicio rápidoSiguiente →Rate limits