Eventos de clave de API (api_key.*)

Ciclo de vida de las claves de API de la cuenta: rotación, cambio de estado y revocación. En todos, data es el shape público de la clave — identificación (id, name, description, keyPrefix), source, scopes y timestamps. El token y su hash nunca aparecen en el payload: el secreto se muestra una única vez, en la respuesta de la creación o de la rotación, y nada derivable de él viaja por webhook. Usa el keyPrefix para identificar de qué credencial se trata.

Campos comunes del data:

{
  "id": "6b4d8e0f-2a3c-4d5e-9f1a-7c9e1b3d5f70",
  "name": "Integración ERP",
  "description": "Sincronización de títulos del ERP",
  "keyPrefix": "kb_a1b2c3d4",
  "source": "api",
  "scopes": ["dunning.dashboard.charges.*"],
  "lastUsedAt": "2026-07-22T18:40:11.000Z",
  "expiresAt": "2026-07-30T12:00:00.000Z",
  "revokedAt": null,
  "createdAt": "2026-01-15T09:00:00.000Z"
}

scopes vacío significa acceso de negocio total (sin lo administrativo); restringido, solo los permisos que coinciden con los wildcards.

api_key.rotated

Se dispara en la rotación (POST /api/v1/api-keys/{id}/rotate). data es la clave antigua, con dos campos extra: successorId (id de la clave sucesora, que hereda nombre, scopes y política de validez) y graceUntil (fin de la ventana de gracia — 7 días por defecto, configurable de 0 a 30 — cuando la clave antigua empieza a responder 401). El expiresAt de la antigua se adelanta a graceUntil, nunca se extiende. El token de la sucesora aparece solo en la respuesta de la rotación, jamás en el webhook.

{
  "event": "api_key.rotated",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "6b4d8e0f-2a3c-4d5e-9f1a-7c9e1b3d5f70",
    "name": "Integración ERP",
    "description": "Sincronización de títulos del ERP",
    "keyPrefix": "kb_a1b2c3d4",
    "source": "api",
    "scopes": ["dunning.dashboard.charges.*"],
    "lastUsedAt": "2026-07-22T18:40:11.000Z",
    "expiresAt": "2026-07-30T12:00:00.000Z",
    "revokedAt": null,
    "createdAt": "2026-01-15T09:00:00.000Z",
    "successorId": "9c1e3f5a-7b2d-4c6e-8a0f-1d3f5b7c9e21",
    "graceUntil": "2026-07-30T12:00:00.000Z"
  }
}

Suscribe este evento para saber que hay un cambio de secreto en curso en tus integraciones — después de graceUntil, las llamadas con la clave antigua fallan.

api_key.status_changed

Se dispara en una transición de estado de la clave, con previousStatus y newStatus además de los campos comunes. Hoy se emite en la revocación ("active" → "revoked"), junto al hecho terminal api_key.revoked; trátalo de forma tolerante — pueden agregarse otras transiciones.

{
  "event": "api_key.status_changed",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "6b4d8e0f-2a3c-4d5e-9f1a-7c9e1b3d5f70",
    "name": "Integración ERP",
    "description": "Sincronización de títulos del ERP",
    "keyPrefix": "kb_a1b2c3d4",
    "source": "api",
    "scopes": ["dunning.dashboard.charges.*"],
    "lastUsedAt": "2026-07-22T18:40:11.000Z",
    "expiresAt": "2026-07-30T12:00:00.000Z",
    "revokedAt": "2026-07-23T12:00:00.000Z",
    "createdAt": "2026-01-15T09:00:00.000Z",
    "previousStatus": "active",
    "newStatus": "revoked"
  }
}

api_key.revoked

Se dispara en la revocación (DELETE /api/v1/api-keys/{id}) — a diferencia de la rotación, no hay ventana de gracia: la clave empieza a responder 401 de inmediato. data es el shape común con revokedAt completado.

{
  "event": "api_key.revoked",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "6b4d8e0f-2a3c-4d5e-9f1a-7c9e1b3d5f70",
    "name": "Integración ERP",
    "description": "Sincronización de títulos del ERP",
    "keyPrefix": "kb_a1b2c3d4",
    "source": "api",
    "scopes": ["dunning.dashboard.charges.*"],
    "lastUsedAt": "2026-07-22T18:40:11.000Z",
    "expiresAt": "2026-07-30T12:00:00.000Z",
    "revokedAt": "2026-07-23T12:00:00.000Z",
    "createdAt": "2026-01-15T09:00:00.000Z"
  }
}