Saltar al contenido principal

Gestión de Claves API

La interfaz de Gestión de Claves API proporciona una interfaz web para crear, monitorear y gestionar claves API utilizadas para el acceso programático a la API de OmniCRM.

::: note ::: title Nota :::

Para conceptos generales de autenticación API y ejemplos de uso, consulta concepts_api. :::

Descripción General​

Las claves API permiten una autenticación segura y de larga duración para:

  • Integraciones de servidor a servidor
  • Scripts de automatización
  • Aplicaciones de terceros
  • Tareas programadas y trabajos cron
  • Sistemas de monitoreo externos

A diferencia de los tokens JWT (que expiran después de minutos/horas), las claves API permanecen válidas hasta que se revoquen manualmente o hasta su fecha de expiración.

Accediendo a la Gestión de Claves API​

Navega a:

O directamente:

Permiso Requerido: MANAGE_API_KEYS (rol de administrador)

Vista de Lista de Claves API​

La página principal muestra todas las claves API en un formato de tabla:

Columnas:

  • Nombre - Etiqueta descriptiva para la clave API (por ejemplo, "Sistema de Aprovisionamiento", "Herramienta de Monitoreo")
  • Creado Por - Nombre de usuario de la persona que creó la clave
  • Clave API - La cadena de clave real (parcialmente enmascarada por seguridad)
  • Estado - Activa, Expirada o Revocada
  • Fecha de Creación - Cuando se generó la clave
  • Fecha de Expiración - Cuando la clave expirará automáticamente
  • Acciones - Botones Editar, Eliminar, Regenerar

Ejemplo de Visualización:

Widgets del Tablero​

En la parte superior de la página, se muestran estadísticas resumidas:

  • Total de Claves API - Conteo de todas las claves API (activas e inactivas)
  • Claves Activas - Claves actualmente válidas
  • Expirando Pronto - Claves que expiran en los próximos 30 días
  • Claves Expiradas - Claves que han pasado su fecha de expiración

Creando una Clave API​

Paso 1: Haz clic en "Agregar Clave API"

Haz clic en el botón + Agregar en la parte superior derecha de la lista de Claves API.

Paso 2: Completa los Detalles

Aparece un formulario modal solicitando:

Nombre: ________________________

: (por ejemplo, "Sistema de Aprovisionamiento")

Descripción: __________________

: (Opcional - propósito de esta clave)

Fecha de Expiración: [Selector de Fecha]

: (Opcional - dejar en blanco para no tener expiración)

Permisos: ☐ Ver Clientes ☐ Crear Clientes ☐ Ver Servicios ☐ Crear Servicios ☐ Aprovisionamiento ☐ Ver Inventario ☑ Administrador (todos los permisos)

[Cancelar] [Generar Clave]

Guías de Campo:

Nombre (requerido)

  • Identificador corto y descriptivo
  • Ejemplos: "Sistema de Aprovisionamiento", "Integración de Facturación", "Monitoreo"
  • Usado en registros de auditoría y mostrado en la lista

Descripción (opcional)

  • Explicación más detallada
  • Ejemplos: "Usado por el servidor de aprovisionamiento de Ansible", "Sincronización de facturación de terceros"
  • Ayuda a futuros administradores a entender el propósito de la clave

Fecha de Expiración (opcional)

  • Si está en blanco: La clave nunca expira (no recomendado)
  • Si se establece: La clave se vuelve automáticamente inválida después de esta fecha
  • Recomendado: Establecer expiración por seguridad (90 días a 1 año)

Permisos

  • Selecciona permisos específicos o marca "Administrador" para acceso completo
  • Sigue el mismo modelo de permisos basado en roles que las cuentas de usuario
  • Mejor Práctica: Asigna el mínimo de permisos necesarios

Paso 3: Generar y Copiar Clave

Después de hacer clic en "Generar Clave", el sistema muestra la nueva clave API creada:

⚠️ ¡Copia esta clave ahora - no se mostrará de nuevo!

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

[Copiar al Portapapeles]

[Cerrar]

::: warning ::: title Advertencia :::

¡Guarda la clave API inmediatamente!

Una vez que cierres este diálogo, la clave completa no podrá ser recuperada nuevamente. Solo verás una versión enmascarada (sk_live_...XYZ) en la vista de lista.

Si pierdes la clave, debes regenerarla, lo que invalida la clave antigua y puede romper integraciones existentes. :::

Paso 4: Configura Tu Aplicación

Usa la clave API en las solicitudes de tu aplicación:

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

O en variables de entorno:

export CRM_API_KEY="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Gestionando Claves Existentes​

Visualizando Detalles de la Clave​

Haz clic en cualquier nombre de clave API para ver todos los detalles:

  • Nombre completo de la clave y descripción
  • Marca de tiempo de creación
  • Nombre de usuario del creador
  • Permisos asociados
  • Estadísticas de uso (si están implementadas)
  • Registros de acceso recientes

Regenerando una Clave API​

Si una clave API está comprometida o perdida, regénérala:

  1. Haz clic en el ⋮ (tres puntos) en la columna de Acciones
  2. Selecciona "Regenerar Clave"
  3. Confirma la acción

::: warning ::: title Advertencia :::

Regenerar invalida la clave antigua inmediatamente.

Cualquier aplicación que use la clave antigua dejará de funcionar. Actualiza todas las integraciones con la nueva clave antes de regenerar. :::

Lo que Ocurre:

  • La clave antigua es revocada
  • Se genera una nueva clave con los mismos permisos
  • Se muestra la nueva clave (cópiala inmediatamente)
  • El nombre, la descripción y los permisos permanecen sin cambios

Revocando (Eliminando) una Clave API​

Para eliminar permanentemente una clave API:

  1. Haz clic en el ⋮ (tres puntos) en la columna de Acciones
  2. Selecciona "Eliminar"
  3. Confirma la eliminación

Lo que Ocurre:

  • La clave es revocada inmediatamente
  • Todas las solicitudes que usen esta clave devuelven 401 Unauthorized
  • La clave es eliminada de la base de datos
  • No se puede deshacer - la clave no puede ser recuperada

Cuándo Revocar:

  • La integración ya no es necesaria
  • La clave ha sido comprometida
  • El sistema que usa la clave ha sido desmantelado
  • Reemplazando con una nueva clave con diferentes permisos

Editando Detalles de la Clave API​

Para modificar los detalles de una clave API:

  1. Haz clic en el ⋮ (tres puntos) en la columna de Acciones
  2. Selecciona "Editar"
  3. Actualiza el nombre, la descripción, la expiración o los permisos
  4. Haz clic en "Guardar Cambios"

Campos Editables:

  • Nombre
  • Descripción
  • Fecha de expiración
  • Permisos

No Editables:

  • El valor de la clave en sí (usa Regenerar para cambiar)
  • Fecha de creación
  • Creado por usuario

Estado de la Clave API​

Las claves API pueden tener varios estados:

Activa

  • La clave es válida y puede ser utilizada
  • Dentro de la fecha de expiración (o sin expiración establecida)
  • No revocada manualmente
  • Mostrada con insignia verde

Expirando Pronto

  • Activa pero expirará en los próximos 30 días
  • Mostrada con insignia naranja/de advertencia
  • Considera rotar antes de la expiración

Expirada

  • Pasada la fecha de expiración
  • Ya no acepta autenticación
  • Mostrada con insignia roja
  • Puede ser eliminada o la expiración extendida

Revocada

  • Eliminada/deshabilitada manualmente
  • Permanentemente inválida
  • Ya no se muestra en la lista activa

Filtrado y Búsqueda​

La lista de Claves API soporta:

Búsqueda:

Buscar por nombre, descripción o clave parcial:

Filtrar por Estado:

Desplegable de filtro para mostrar:

  • Todas las Claves
  • Solo Activas
  • Expirando Pronto (próximos 30 días)
  • Expiradas

Ordenar:

Haz clic en los encabezados de columna para ordenar por:

  • Nombre
  • Fecha de Creación
  • Fecha de Expiración
  • Creado Por

Mejores Prácticas de Seguridad​

Generación de Claves API​

  • Longitud: Las claves deben tener al menos 32 caracteres (el sistema lo impone)
  • Aleatoriedad: Generadas utilizando generadores de números aleatorios criptográficamente seguros
  • Formato: Generalmente prefijadas (por ejemplo, sk_live_) para identificación

Almacenamiento de Claves API​

En el CRM:

  • Las claves son encriptadas antes de ser almacenadas (como contraseñas)
  • La clave completa solo se muestra una vez durante la creación
  • La base de datos almacena el hash para verificación
  • Incluso los administradores no pueden recuperar la clave completa más tarde

En Tu Aplicación:

  • Almacena en variables de entorno, no en el código
  • Usa sistemas de gestión de secretos (AWS Secrets Manager, HashiCorp Vault)
  • Nunca comités claves en el control de versiones
  • Rota las claves periódicamente (cada 90-365 días)

Gestión de Permisos​

  • Principio de Menor Privilegio - Solo otorga los permisos necesarios
  • Evita crear claves de administrador a menos que sea absolutamente necesario
  • Usa claves separadas para diferentes sistemas/purposes
  • Revisa los permisos regularmente

Monitoreo y Auditoría​

  • Monitorea el uso de claves API a través de registros de actividad
  • Configura alertas para patrones de acceso inusuales
  • Revisa las marcas de tiempo de "último uso" regularmente
  • Elimina claves no utilizadas

Rotación de Claves​

Establece una política de rotación de claves:

  1. Crea una nueva clave con los mismos permisos
  2. Actualiza las aplicaciones para usar la nueva clave
  3. Monitorea para asegurar que la clave antigua ya no se use
  4. Revoca la clave antigua después del período de gracia

Resolución de Problemas​

"401 Unauthorized" al usar la clave API

  • Causa: Clave inválida, expirada o incorrecta
  • Solución:
    • Verifica que la clave esté copiada correctamente (sin espacios adicionales)
    • Verifica el estado de la clave (Activa vs. Expirada)
    • Confirma que la clave tenga los permisos requeridos
    • Asegúrate de usar el encabezado X-API-KEY (no Authorization)

"Clave API no encontrada" después de la creación

  • Causa: La clave puede haber sido creada pero no almacenada correctamente
  • Solución:
    • Verifica la lista de claves API para la nueva entrada
    • Si falta, crea una nueva clave
    • Reporta el problema al administrador

Clave API expirando pronto

  • Causa: La fecha de expiración se acerca (dentro de 30 días)
  • Solución:
    • Crea una nueva clave con expiración extendida
    • Actualiza las aplicaciones para usar la nueva clave
    • Revoca la clave antigua después de la migración

No se puede eliminar la clave API

  • Causa: Puede estar protegida o en uso
  • Solución:
    • Asegúrate de tener permisos de administrador
    • Verifica si la clave está bloqueada/protegida
    • Contacta al administrador si el problema persiste

Puntos Finales de API (para Gestión Programática)​

Las claves API también pueden ser gestionadas a través de la API (requiere permisos de administrador):

Listar Claves API

GET /crm/api-keys
Authorization: Bearer <admin-token>

Crear Clave API

POST /crm/api-keys
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Nueva Integración",
  "description": "Sincronización de facturación de terceros",
  "expiry_date": "2026-01-10",
  "permissions": ["view_customer", "view_service"]
}

Respuesta:

{
  "api_key_id": 123,
  "name": "Nueva Integración",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0",
  "status": "active",
  "created": "2025-01-10T10:00:00Z",
  "expiry_date": "2026-01-10T23:59:59Z"
}

Revocar Clave API

DELETE /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>

Actualizar Clave API

PATCH /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Nombre Actualizado",
  "expiry_date": "2026-12-31"
}

Casos de Uso Comunes​

Caso de Uso 1: Integración del Sistema de Aprovisionamiento

Crea una clave API para tu servidor de aprovisionamiento de Ansible:

  1. Navega a Claves API → Agregar
  2. Nombre: "Servidor de Aprovisionamiento de Ansible"
  3. Descripción: "Usado por la automatización de aprovisionamiento"
  4. Permisos: Aprovisionamiento, Ver/Criar Servicios, Ver/Actualizar Inventario
  5. Expiración: 1 año
  6. Copia la clave y añádela a crm_config.yaml de Ansible

Caso de Uso 2: Integración de Facturación de Terceros

Crea una clave de solo lectura para la exportación de facturación:

  1. Nombre: "Sincronización de Facturación - QuickBooks"
  2. Permisos: Ver Clientes, Ver Transacciones, Ver Facturas
  3. Expiración: 90 días (rotar trimestralmente)
  4. Usar en el script de exportación programada

Caso de Uso 3: Monitoreo y Alertas

Crea una clave para la recolección de métricas de Prometheus/Grafana:

  1. Nombre: "Monitoreo - Grafana"
  2. Permisos: Ver Servicios, Ver Aprovisionamiento
  3. Expiración: Nunca (el monitoreo necesita acceso continuo)
  4. Configura en la fuente de datos de Grafana

Caso de Uso 4: API del Portal del Cliente

Crea una clave para el portal de autoservicio del cliente:

  1. Nombre: "Backend del Portal del Cliente"
  2. Permisos: Ver Propio Cliente, Ver Propios Servicios, Crear Pagos
  3. Expiración: 180 días
  4. Usar en llamadas a la API del backend del portal

Documentación Relacionada​

  • concepts_api - Conceptos y ejemplos de autenticación API
  • rbac - Control de acceso basado en roles y permisos
  • 2fa - Autenticación de dos factores para seguridad adicional