Saltar al contenido principal

Crear Clave de API

Crea una nueva clave de API para acceso programático a la API de CallCov. La clave completa solo se muestra una vez durante la creación y no puede recuperarse después.

Endpoint​

POST /api/v1/api-keys/

Autenticación​

Requiere token JWT (autenticación Bearer).

Solo JWT

Las claves de API solo pueden crearse usando autenticación JWT. No puedes crear una clave de API usando otra clave de API.

Request​

Content-Type​

application/json

Request Body​

CampoTipoRequeridoDescripción
descriptionstringNoDescripción de para qué es esta clave (máx 500 caracteres)

Ejemplo de Request​

{
  "description": "Clave de API de producción para integración de análisis de llamadas"
}

Response​

Response Exitoso (201 Created)​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "key_prefix": "sk_live_abc123",
  "description": "Clave de API de producción para integración de análisis de llamadas",
  "created_at": "2024-01-15T10:30:00Z"
}
¡Guarda tu Clave de API!

El valor de api_key solo se muestra una vez. Guárdalo inmediatamente en un lugar seguro. No vas a poder recuperarlo de nuevo.

Campos del Response​

CampoTipoDescripción
idUUIDIdentificador único de la clave de API
api_keystringClave de API completa (¡se muestra solo una vez!)
key_prefixstringPrimeros 14 caracteres de la clave (para identificación)
descriptionstringTu descripción
created_atdatetimeTimestamp de creación (ISO 8601)

Formato de Clave de API​

Las claves de API siguen el formato: sk_{entorno}_{cadena_aleatoria}

  • sk = Secret Key (Clave Secreta)
  • live = Entorno de producción
  • test = Entorno de prueba (aún no implementado)
  • Cadena aleatoria = 48 caracteres

Ejemplo: sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Límites​

  • Máximo 10 claves de API activas por usuario
  • Para crear más, primero tienes que expirar las claves que no usas

Ejemplos​

curl -X POST https://api.callcov.com/api/v1/api-keys/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
  "description": "Clave de API de producción"
}'

Usando tu Clave de API​

Después de crear una clave de API, usala para autenticación de API:

# En lugar del token JWT
curl https://api.callcov.com/api/v1/analysis/ \
  -H "X-API-Key: sk_live_abc123def456..."

Errores​

400 Bad Request​

Se alcanzó el máximo de claves de API:

{
  "detail": "Se alcanzó el número máximo de claves de API (10). Por favor expirar las claves sin usar."
}

401 Unauthorized​

Token JWT inválido o faltante:

{
  "detail": "No se pudieron validar las credenciales"
}

Mejores Prácticas de Seguridad​

✅ HACER​

  • Guardar inmediatamente: Copia la clave a un administrador de contraseñas seguro
  • Usar variables de entorno: Almacenar en archivos .env (¡nunca hacer commit!)
  • Rotar regularmente: Crear nuevas claves periódicamente y expirar las viejas
  • Usar nombres descriptivos: Ayuda a identificar qué integración usa qué clave
  • Claves separadas por entorno: Claves diferentes para desarrollo, staging, producción

❌ NO HACER​

  • Nunca hacer commit a Git: Claves de API en código = brecha de seguridad
  • Nunca compartir públicamente: No pegar en Slack, Discord, foros
  • Nunca loguear en texto plano: Redactar claves en logs de aplicación
  • Nunca embeber en código del cliente: Solo usar en backend/servidor

Ejemplo: Almacenamiento Seguro​

Variable de Entorno (archivo .env)​

# .env (¡agregar a .gitignore!)
CALLCOV_API_KEY=sk_live_abc123def456...
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('CALLCOV_API_KEY')

AWS Secrets Manager​

import boto3
import json

def get_api_key():
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId='callcov/api-key')
    return json.loads(response['SecretString'])['api_key']

api_key = get_api_key()

Organizando Múltiples Claves​

Crea diferentes claves para diferentes propósitos:

# Desarrollo
description="Desarrollo - Pruebas Locales"

# Staging
description="Staging - Ambiente de QA"

# Producción
description="Producción - Aplicación Principal"

# CI/CD
description="CI/CD - Tests Automatizados"

Esto facilita:

  • Identificar qué clave se está usando
  • Expirar claves comprometidas sin afectar otras
  • Rastrear uso por entorno

Qué Sucede Después de la Creación​

  1. Clave completa devuelta: Guárdala inmediatamente
  2. Clave es hasheada: Solo el hash se almacena en la base de datos
  3. Prefijo guardado: Usado para identificación en la lista de claves
  4. Clave está activa: Puede usarse inmediatamente para requests de API

Ciclo de Vida de la Clave​

Crear Clave → Usar para llamadas de API → Monitorear uso → Expirar cuando ya no se necesite

Relacionado​