Saltar al contenido principal

Autenticación

CallCov soporta dos métodos de autenticación: Claves API (recomendadas para servidor a servidor) y Tokens JWT (para aplicaciones basadas en usuarios).

Autenticación con Clave API​

Las claves API son el método recomendado para integraciones backend. Son simples, seguras y no expiran.

Creando una Clave API​

Crear Clave API
curl -X POST https://api.callcov.com/api/v1/api-keys/ \
  -H "Authorization: Bearer TU_TOKEN_DE_ACCESO" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clave de Servidor de Producción"
  }'

Usando una Clave API​

Incluye tu clave API en el encabezado Authorization con el esquema Bearer:

Usando Clave API
curl -X GET https://api.callcov.com/api/v1/analysis/ \
  -H "Authorization: Bearer sk_live_abc123..."

Formato de Clave API​

  • Prefijo: sk_live_ para producción, sk_test_ para modo prueba
  • Almacenamiento: Guarda de manera segura en variables de entorno, nunca en código
  • Rotación: Rota las claves regularmente por seguridad
Buena Práctica

Guarda las claves API en variables de entorno:

export CALLCOV_API_KEY="sk_live_abc123..."

Autenticación con Token JWT​

Los tokens JWT son ideales para aplicaciones de cara al usuario donde necesitas permisos específicos de usuario.

Flujo de Login​

Paso 1: Iniciar Sesión
curl -X POST https://api.callcov.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@ejemplo.com",
    "password": "ContraseñaSegura123!"
  }'

Respuesta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1800
}

Usando Tokens JWT​

Paso 2: Usar Token de Acceso
curl -X GET https://api.callcov.com/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Expiración de Tokens​

  • Access Token: Expira en 30 minutos
  • Refresh Token: Expira en 7 días

Refrescando Tokens​

Cuando tu token de acceso expire, usa el refresh token para obtener uno nuevo:

Refrescar Token de Acceso
curl -X POST https://api.callcov.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Mejores Prácticas de Seguridad​

1. Usa Solo HTTPS​

Todas las solicitudes API deben usar HTTPS. Las solicitudes HTTP serán rechazadas.

2. Protege tus Claves​

# ✅ Bien: Variable de entorno
export CALLCOV_API_KEY="sk_live_abc123..."

# ❌ Mal: Hardcodeado en código
api_key = "sk_live_abc123..."  # ¡Nunca hagas esto!

3. Rota Claves Regularmente​

Crea nuevas claves API y revoca las antiguas cada 90 días.

4. Usa Diferentes Claves para Diferentes Entornos​

# Desarrollo
sk_test_dev_abc123...

# Staging
sk_test_staging_def456...

# Producción
sk_live_prod_ghi789...

5. Implementa Lógica de Refresco de Token​

No esperes errores 401. Refresca de manera proactiva:

Ejemplo Python: Auto-Refresco
import requests
from datetime import datetime, timedelta

class CallCovClient:
    def __init__(self, email, password):
        self.email = email
        self.password = password
        self.access_token = None
        self.refresh_token = None
        self.token_expires = None
        self.login()

    def login(self):
        response = requests.post(
            'https://api.callcov.com/api/v1/auth/login',
            json={'email': self.email, 'password': self.password}
        )
        data = response.json()
        self.access_token = data['access_token']
        self.refresh_token = data['refresh_token']
        self.token_expires = datetime.now() + timedelta(seconds=data['expires_in'])

    def ensure_valid_token(self):
        # Refrescar 5 minutos antes de expiración
        if datetime.now() >= self.token_expires - timedelta(minutes=5):
            self.refresh()

    def refresh(self):
        response = requests.post(
            'https://api.callcov.com/api/v1/auth/refresh',
            json={'refresh_token': self.refresh_token}
        )
        data = response.json()
        self.access_token = data['access_token']
        self.token_expires = datetime.now() + timedelta(seconds=data['expires_in'])

    def make_request(self, method, endpoint, **kwargs):
        self.ensure_valid_token()
        headers = kwargs.get('headers', {})
        headers['Authorization'] = f'Bearer {self.access_token}'
        kwargs['headers'] = headers
        return requests.request(method, f'https://api.callcov.com{endpoint}', **kwargs)

Revocando Acceso​

Revocar Claves API​

curl -X DELETE https://api.callcov.com/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer TU_TOKEN_DE_ACCESO"

Cerrar Sesión (Invalidar Tokens)​

Los tokens JWT no pueden ser revocados del lado del servidor pero expirarán automáticamente. Para cerrar sesión inmediatamente, elimina los tokens del lado del cliente.

Errores de Autenticación​

Código de EstadoErrorSolución
401Token inválido o faltanteIncluye un encabezado Authorization válido
401Token expiradoRefresca tu token de acceso
403Permisos insuficientesVerifica los permisos de tu cuenta

Próximos Pasos​