Saltar al contenido principal

Guía de Autenticación

La API de CallCov utiliza claves de API para autenticar las solicitudes. Esta guía cubre todo lo que necesitas saber sobre cómo asegurar tu integración con nuestra API.

Resumen​

Todas las solicitudes a la API deben incluir tu clave de API en los headers de la solicitud. Tu clave de API identifica tu cuenta y proporciona acceso a tus recursos.

Mejores Prácticas de Seguridad

Nunca expongas tus claves de API en código del lado del cliente, repositorios públicos o sistemas de control de versiones. Siempre mantenlas seguras en tu servidor.

Obtener tu Clave de API​

  1. Inicia sesión en tu Panel de CallCov
  2. Navega a Configuración → Claves de API
  3. Haz clic en Generar Nueva Clave
  4. Copia tu clave inmediatamente (no se mostrará nuevamente)
  5. Guárdala de forma segura en tus variables de entorno

Métodos de Autenticación​

Clave de API en Header (Recomendado)​

Incluye tu clave de API en el header X-API-Key con cada solicitud:

import requests


API_KEY = "your_api_key_here"
API_URL = "https://api.callcov.com/api/v1"


headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json"
}


response = requests.get(
  f"{API_URL}/calls",
  headers=headers
)


print(response.json())

Mejores Prácticas con Variables de Entorno​

Guarda tu clave de API como una variable de entorno para mantenerla segura:

import os
from dotenv import load_dotenv


# Cargar variables de entorno desde archivo .env
load_dotenv()


API_KEY = os.getenv("CALLCOV_API_KEY")


if not API_KEY:
  raise ValueError("Variable de entorno CALLCOV_API_KEY no configurada")


# Usa API_KEY en tus solicitudes
headers = {"X-API-Key": API_KEY}

Crear un Cliente Reutilizable​

Para aplicaciones en producción, crea una clase de cliente reutilizable que maneje la autenticación automáticamente:

import os
import requests
from typing import Optional, Dict, Any


class CallCovClient:
  """Cliente reutilizable para la API de CallCov"""


  def __init__(self, api_key: Optional[str] = None):
      self.api_key = api_key or os.getenv("CALLCOV_API_KEY")
      self.base_url = "https://api.callcov.com/api/v1"


      if not self.api_key:
          raise ValueError("Se requiere clave de API")


      self.session = requests.Session()
      self.session.headers.update({
          "X-API-Key": self.api_key,
          "Content-Type": "application/json"
      })


  def get(self, endpoint: str, params: Optional[Dict] = None) -> Dict[Any, Any]:
      """Realizar solicitud GET"""
      url = f"{self.base_url}{endpoint}"
      response = self.session.get(url, params=params)
      response.raise_for_status()
      return response.json()


  def post(self, endpoint: str, data: Dict[Any, Any]) -> Dict[Any, Any]:
      """Realizar solicitud POST"""
      url = f"{self.base_url}{endpoint}"
      response = self.session.post(url, json=data)
      response.raise_for_status()
      return response.json()


# Uso
client = CallCovClient()
calls = client.get("/calls")
print(calls)

Probar tu Autenticación​

Verifica que tu clave de API funciona correctamente con una solicitud de prueba simple:

import requests


def test_authentication(api_key):
  """Probar si la clave de API es válida"""
  headers = {"X-API-Key": api_key}


  try:
      response = requests.get(
          "https://api.callcov.com/api/v1/health",
          headers=headers,
          timeout=10
      )


      if response.status_code == 200:
          print("✓ Autenticación exitosa!")
          return True
      elif response.status_code == 401:
          print("✗ Autenticación falló - Clave de API inválida")
          return False
      else:
          print(f"✗ Respuesta inesperada: {response.status_code}")
          return False


  except requests.exceptions.RequestException as e:
      print(f"✗ Error de conexión: {e}")
      return False


# Probar tu clave
api_key = "your_api_key_here"
test_authentication(api_key)

Respuestas de Error​

401 No Autorizado​

Tu clave de API está ausente o es inválida:

{
  "error": {
    "code": "unauthorized",
    "message": "Clave de API inválida o ausente"
  }
}

Soluciones:

  • Verifica que la clave de API sea correcta
  • Verifica que el nombre del header sea exactamente X-API-Key
  • Asegúrate de que no haya espacios adicionales o caracteres extra

403 Prohibido​

Tu clave de API es válida pero carece de permisos para este recurso:

{
  "error": {
    "code": "forbidden",
    "message": "Permisos insuficientes para este recurso"
  }
}

Soluciones:

  • Verifica que tu plan de cuenta soporte esta función
  • Contacta a soporte si crees que esto es un error

Mejores Prácticas de Seguridad​

✅ Sí hacer​

  • Guardar claves en variables de entorno, nunca en el código
  • Usar HTTPS para todas las solicitudes a la API
  • Rotar claves regularmente (cada 90 días recomendado)
  • Usar claves separadas para desarrollo y producción
  • Monitorear el uso de la API para detectar patrones inusuales
  • Revocar claves comprometidas inmediatamente

❌ No hacer​

  • Nunca hacer commit de claves al control de versiones (Git, SVN, etc.)
  • Nunca exponer claves en código del lado del cliente (JavaScript, aplicaciones móviles)
  • Nunca compartir claves por email o chat
  • Nunca registrar claves de API en logs de aplicación
  • Nunca usar la misma clave en múltiples aplicaciones

Gestión de Claves​

Rotación de Claves​

Para rotar tu clave de API de forma segura:

  1. Genera una nueva clave en el panel de control
  2. Actualiza tu entorno de producción con la nueva clave
  3. Prueba que la nueva clave funciona correctamente
  4. Revoca la clave antigua después de confirmar que todo funciona

Revocación de Claves​

Si sospechas que una clave ha sido comprometida:

  1. Revoca la clave inmediatamente en el panel de control
  2. Genera una nueva clave
  3. Actualiza todas las aplicaciones que usan la clave antigua
  4. Revisa los logs de la API para detectar actividad sospechosa

Límites de Frecuencia​

Todas las claves de API tienen límites de frecuencia basados en tu plan:

PlanSolicitudes/MinutoSolicitudes/Día
Gratis101,000
Starter6010,000
Business300100,000
EnterprisePersonalizadoPersonalizado

La información de límite de frecuencia se incluye en los headers de respuesta:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699564800

Próximos Pasos​

¿Necesitas Ayuda?​