API Keys.

Cómo autenticar integraciones programáticas con Vericto: scopes disponibles, ciclo de vida de las claves, integración con CI/CD y mejores prácticas de seguridad.

Resumen

Las API keys son el mecanismo de autenticación para integraciones no interactivas: pipelines de CI/CD, scripts de automatización, el CLI de Vericto y cualquier sistema que necesite evaluar queries o leer el audit trail sin un usuario humano detrás.

Cada key tiene un conjunto de scopes que define exactamente qué puede hacer. Una key con solo el scope ci no puede leer el audit trail ni acceder al dashboard. Esto permite aplicar el principio de mínimo privilegio en cada integración.

El plaintext de la key se muestra una sola vez. Al crear una key, cópiala y guárdala en tu gestor de secretos antes de cerrar la ventana. Vericto solo almacena el hash y no puede recuperar el valor original.

Scopes disponibles

Cada key puede tener uno o más scopes. Asigna solo los que la integración necesita:

Scope Qué permite Caso de uso típico
ci Ejecutar el dry-run del CLI en modo CI: evalúa queries contra el ruleset sin modificar la base de datos. GitHub Actions, GitLab CI, Jenkins — validar queries antes de un deploy.
proxy Autenticar el proxy TCP de Vericto para reportar telemetría de queries interceptadas al backend. El contenedor del proxy en Docker/Kubernetes. Necesita VERICTO_API_KEY.
telemetry:write Enviar eventos de query directamente al endpoint POST /api/v1/ingest/events. Integraciones HTTP que envían telemetría sin pasar por el proxy TCP.
audit:read Leer el audit trail vía API: listar eventos, filtrar por rango de fechas y estado. Scripts de compliance que exportan el audit trail a un SIEM o data warehouse.
rules:read Consultar el ruleset activo del workspace. Herramientas de inventario que necesitan conocer las reglas activas sin acceso al dashboard.

Ciclo de vida de una key

Crear

Ve a Dashboard → API Keys → New API key. Dale un nombre descriptivo (ej. GitHub Actions CI), selecciona los scopes necesarios y, opcionalmente, establece una fecha de expiración en días. Al crear, copia la key — solo se muestra una vez.

Rotar

La rotación genera una key nueva con los mismos scopes y revoca la anterior de inmediato. Úsala para el proceso de rotación periódica sin interrumpir el servicio: actualiza el secreto en tu CI/CD antes de confirmar la rotación en Vericto, o hazlo en la misma ventana de deployment.

Revocar

La revocación es permanente e irreversible. La key deja de funcionar de inmediato. Úsala cuando una key se ha comprometido o cuando ya no se necesita la integración. Si solo quieres reemplazarla, usa Rotar en su lugar.

Expiración automática

Puedes fijar un TTL en días al crear la key (ej. 90 días). Después de ese periodo, la key expira automáticamente. Vericto no envía notificación de expiración — programa la rotación antes de la fecha límite. El campo Expira en el dashboard muestra la fecha exacta.

Integración con CI/CD

El caso de uso más habitual es validar queries SQL antes de un deploy en el pipeline de CI. El CLI de Vericto evalúa cada query en el archivo de migración o seeds contra el ruleset activo y falla el build si detecta alguna destructiva.

GitHub Actions

# .github/workflows/vericto-check.yml
name: Vericto SQL check
on: [pull_request]

jobs:
  vericto:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Vericto dry-run
        env:
          VERICTO_API_KEY: ${{ secrets.VERICTO_API_KEY }}
          VERICTO_WORKSPACE_ID: ${{ vars.VERICTO_WORKSPACE_ID }}
        run: |
          npx vericto-cli check \
            --file migrations/latest.sql \
            --dialect postgres \
            --workspace $VERICTO_WORKSPACE_ID

Guarda la API key como secret en tu repositorio (VERICTO_API_KEY), no como variable de entorno pública. El VERICTO_WORKSPACE_ID puede ser una variable pública ya que no es un secreto.

Mejores prácticas de seguridad

Almacena el plaintext en un gestor de secretos

Nunca guardes el plaintext de una API key en el código fuente, en .env commiteados al repositorio ni en la documentación interna en texto plano. Úsa tu gestor de secretos (AWS Secrets Manager, HashiCorp Vault, GitHub Secrets, 1Password Teams) desde el primer momento.

Una key por integración, scopes mínimos

Crea una key distinta para cada integración y asígnale solo los scopes que esa integración necesita. El pipeline de CI solo necesita ci. El proxy TCP solo necesita proxy. Si una key se compromete, el radio de impacto queda limitado a los scopes de esa key.

Rotación periódica

Rota todas las API keys al menos cada 90 días, o inmediatamente si sospechas que una ha sido comprometida. El proceso de rotación en Vericto es atómico: la key nueva es válida antes de que la antigua deje de funcionar, si gestionas la rotación correctamente en tu CI/CD.

Offboarding de ingenieros

Las API keys no están asociadas a un usuario individual — pertenecen al workspace. Sin embargo, cuando alguien que tenía acceso a las keys abandona el equipo, rota todas las keys activas como medida de precaución, especialmente si tienen acceso a audit:read o rules:read.

Preguntas frecuentes

¿Cuántas API keys puedo tener?

No hay límite en el número de API keys por workspace en ningún plan. Crea tantas como necesites — una por integración es la práctica recomendada.

¿Puedo ver el valor de una key creada previamente?

No. Vericto almacena solo el hash SHA-256 del plaintext. Si pierdes la key, crea una nueva (puedes usar Rotar para mantener los mismos scopes) y actualiza el secreto en tu integración.

¿Las API keys tienen acceso al dashboard del navegador?

No. Las API keys solo autentican llamadas a la API REST de Vericto. No puedes iniciar sesión en el dashboard con una API key — eso requiere autenticación con email/contraseña o SSO.

¿Cómo sé si una key está siendo usada?

El dashboard muestra la fecha del último uso de cada key en la lista de API Keys. Para el proxy TCP, cada query interceptada aparece en el audit trail con el database_id asociado a la key.

¿Quién puede crear y gestionar API keys?

Solo los owners y admins del workspace pueden crear, rotar y revocar API keys. Los members y viewers no tienen acceso a esta sección.