Eventos de chave de API (api_key.*)

Ciclo de vida das chaves de API da conta: rotação, mudança de status e revogação. Em todos, data é o shape público da chave — identificação (id, name, description, keyPrefix), source, scopes e timestamps. O token e o hash nunca aparecem no payload: o secret é exibido uma única vez, na resposta da criação ou da rotação, e nada derivável dele trafega por webhook. Use o keyPrefix para identificar de qual credencial se trata.

Campos comuns do data:

{
  "id": "6b4d8e0f-2a3c-4d5e-9f1a-7c9e1b3d5f70",
  "name": "Integração ERP",
  "description": "Sincronização de títulos do 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 vazio significa acesso de negócio total (sem o administrativo); restrito, só as permissões que casam com os wildcards.

api_key.rotated

Dispara na rotação (POST /api/v1/api-keys/{id}/rotate). data é a chave antiga, com dois campos extras: successorId (id da chave sucessora, que herda nome, escopos e política de validade) e graceUntil (fim da janela de carência — 7 dias por padrão, configurável de 0 a 30 — quando a chave antiga passa a responder 401). O expiresAt da antiga é antecipado para graceUntil, nunca estendido. O token da sucessora aparece só na resposta da rotação, jamais no 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": "Integração ERP",
    "description": "Sincronização de títulos do 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"
  }
}

Assine este evento para saber que existe uma troca de secret em andamento nas suas integrações — depois de graceUntil, chamadas com a chave antiga falham.

api_key.status_changed

Dispara numa transição de status da chave, com previousStatus e newStatus além dos campos comuns. Hoje é emitido na revogação ("active" → "revoked"), junto do fato terminal api_key.revoked; trate de forma tolerante — outras transições podem ser adicionadas.

{
  "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": "Integração ERP",
    "description": "Sincronização de títulos do 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

Dispara na revogação (DELETE /api/v1/api-keys/{id}) — diferente da rotação, não há carência: a chave passa a responder 401 imediatamente. data é o shape comum com revokedAt preenchido.

{
  "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": "Integração ERP",
    "description": "Sincronização de títulos do 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"
  }
}