Skip to main content
Version: next

Audit

Overview​

Audit provides visibility into important security-relevant actions and alert delivery outcomes. Use it to investigate who did what and when, and to prove compliance.

  • Event types: authentication, token create / update / delete, workspace membership changes, CertOps certificate and executor events, auto-sync runs, alert delivery results (success/failure), weekly digest sends, WhatsApp tests, settings updates, integrations, and imports.
  • Retention: depends on your deployment policy and log storage configuration.
  • Export: audit logs can be exported as CSV or JSON for compliance reporting and external analysis.

Workspace scope​

View events tied to the currently selected workspace. Managers and admins can filter by date and event type to focus on relevant activity.

  • Token changes, member invites/removals, settings updates.
  • Alert delivery outcomes for tokens in this workspace.

Organization scope​

Admins can aggregate events across all admin-owned workspaces to spot trends and investigate cross-workspace issues.

  • Organization-wide filters and export.
  • Combine with Usage to correlate incidents and thresholds.

Event catalog​

Each event records "occurredAt", "actor_user_id", "subject_user_id", "action", "target_type", "target_id", "channel", "metadata", and "workspace_id" (when applicable).

Authentication​

  • LOGIN_SUCCESS metadata: { method }
  • LOGIN_SUCCESS_2FA metadata: { method }
  • LOGIN_FAILED metadata: { email, reason }
  • LOGOUT
  • REGISTRATION metadata: { method }. method is "invite_token" when the account was created by accepting a workspace invitation, or "self_signup" otherwise.
  • TWO_FACTOR_ENABLED
  • TWO_FACTOR_DISABLED
  • EMAIL_VERIFICATION_SENT
  • EMAIL_VERIFICATION_RESENT
  • EMAIL_VERIFICATION_FAILED
  • EMAIL_VERIFIED
  • PASSWORD_RESET_REQUESTED
  • PASSWORD_RESET_COMPLETED
  • PASSWORD_CHANGED

Workspace & RBAC​

  • WORKSPACE_CREATED metadata: { name, kind }
  • WORKSPACE_RENAMED metadata: { before.name, after.name }
  • WORKSPACE_DELETED
  • MEMBER_INVITED_OR_UPDATED metadata: { role, email, workspace_name, recipient_type }. Emitted synchronously when an invitation or direct membership is created. recipient_type is "existing_user" when the email already has a TokenTimer account (membership created directly) or "invitation" when a pending invitation row was written for a new email.
  • INVITE_EMAIL_SENT metadata: { role, email, workspace_name }. Emitted only after the invitation email was handed off to the SMTP transport successfully. Absence of this event after MEMBER_INVITED_OR_UPDATED means the email step failed and the operator should check mail logs.
  • INVITATION_CANCELLED metadata: { email, role, workspace_name, invitation_id }. Emitted when a pending invitation is removed via DELETE /api/v1/workspaces/:id/invitations/:invitationId. Accepted invitations are never cancelled by this endpoint.
  • MEMBER_ROLE_CHANGED metadata: { role }
  • MEMBER_REMOVED
  • WORKSPACE_MEMBERSHIP_ACCEPTED
  • WORKSPACE_ALERT_SETTINGS_UPDATED
  • SYSTEM_ADMIN_CHANGED metadata: { is_admin }. Instance-level (not workspace-scoped); recorded when a platform administrator grants or revokes another user's admin flag.

Tokens​

  • TOKEN_CREATED metadata: { name, type, category }
  • TOKEN_UPDATED metadata: { fields, changes }
  • TOKEN_DELETED metadata: { name, reason }; deletions performed by obsolete-token cleanup also include { location, provider } and use reason: "import_cleanup" (manual imports) or reason: "auto_sync_cleanup" (auto-sync runs)
  • TOKENS_TRANSFERRED_BETWEEN_WORKSPACES
  • TOKENS_REASSIGNED_CONTACT_GROUP

Contacts & WhatsApp​

  • WORKSPACE_CONTACT_CREATED metadata: { contact_id, phone_masked }
  • WORKSPACE_CONTACT_UPDATED metadata: { contact_id, fields_updated }
  • WORKSPACE_CONTACT_DELETED metadata: { contact_id }
  • WHATSAPP_TEST_SENT
  • WHATSAPP_TEST_SENT_TEMPLATE
  • WHATSAPP_TEST_FAILED
  • WHATSAPP_TEST_FAILED_TEMPLATE
  • WHATSAPP_TEST_RATE_LIMITED
  • WHATSAPP_TEST_ERROR

Alert delivery​

  • ALERT_QUEUED metadata: { daysUntil, threshold, dueDate }
  • ALERT_CHANNELS_UPDATED metadata: { alertKey, from, to }
  • ALERT_NOT_QUEUED_NO_CHANNEL metadata: { reason }
  • ALERT_SENT metadata: { days, channels }
  • ALERT_SEND_FAILED metadata: { days, error, attempts }
  • ALERT_PARTIAL_SUCCESS metadata: { channel, errors }
  • ALERT_RETRY_SCHEDULED metadata: { days, next_attempt_at, remaining_channels }
  • ALERT_BLOCKED_MAX_ATTEMPTS metadata: { days, attempts_email, attempts_webhooks, attempts_whatsapp }
  • ALERT_BLOCKED_WHATSAPP_ERROR metadata: { days }
  • ALERT_MANUAL_RETRY
  • WEEKLY_DIGEST_SENT metadata: { contact_group_id, contact_group_name, tokens_count, channels, week_start_date }

System operations​

  • ALERTS_BULK_REQUEUED
  • WHATSAPP_TEST_SENT and related test events

User settings & integrations​

  • ALERT_PREFS_UPDATED metadata: { fields_updated }
  • INTEGRATION_SCAN metadata: { provider, region, success, tokens_found }
  • INTEGRATION_DETECT_REGIONS metadata: { provider, regions_found }
  • TOKEN_IMPORTED metadata: { source, name, type }
  • TOKENS_IMPORTED metadata: { source, count, method }

Auto-Sync​

  • AUTO_SYNC_CREATED metadata: { provider, frequency, timezone }
  • AUTO_SYNC_UPDATED metadata: { provider, fields_updated }
  • AUTO_SYNC_DELETED metadata: { provider }
  • AUTO_SYNC_TRIGGERED metadata: { provider }
  • AUTO_SYNC_FAILED metadata: { provider, error }. Emitted by the worker when a scheduled sync run fails; check error and the worker logs for the underlying cause.

CertOps​

  • CERTOPS_API_TOKEN_CREATED metadata: { api_token_id, token_prefix, name, scopes, status, expires_at }. Emitted when a workspace admin creates a machine API token for a CertOps executor.
  • CERTOPS_API_TOKEN_REVOKED metadata: { api_token_id, token_prefix, name, scopes, status, revoked_at }.
  • CERTOPS_CERTIFICATE_REGISTERED / CERTOPS_CERTIFICATE_IMPORTED metadata: { source, count, certificate_ids, fingerprints_sha256 }. source is "api" for CertOps API registrations or "import" for dashboard PEM imports.
  • CERTOPS_CERTIFICATE_RETIRED metadata: { managedCertificateId, tokenId, status, reason, fingerprintSha256 }.
  • CERTOPS_JOB_CREATED_MANUAL metadata: { operation, subjectType, subjectId, source }. Emitted when a workspace manager creates an executor job manually from the dashboard or POST .../certops/jobs. source is always "api".
  • CERTOPS_EXECUTOR_EVENT_ACCEPTED metadata: { apiTokenId, executorEventId, eventType, jobId, logId, status, evidenceIds }. Emitted for every accepted job lifecycle event posted by a CertOps executor using a machine API token.
  • CERTOPS_EVIDENCE_ACCEPTED metadata: same fields as CERTOPS_EXECUTOR_EVENT_ACCEPTED. Emitted alongside it when the accepted event carried evidence.
  • CERTOPS_EVIDENCE_REJECTED metadata: { apiTokenId, jobId, eventId, eventType, rejectionCode, routeFamily }.
  • CERTOPS_KEY_MATERIAL_REJECTED — emitted whenever a request is rejected because it contained private key material; TokenTimer never accepts or stores private keys. Dashboard/API requests use { code: "PRIVATE_KEY_MATERIAL_REJECTED", method, path, body_type }; CertOps executor events (machine token) use { code: "PRIVATE_KEY_MATERIAL_REJECTED", method, routeFamily, apiTokenId }.
  • CERTOPS_GENERIC_SECRET_REDACTION_APPLIED metadata: { ...executor event fields, redactionApplied: true, redactionCount, redactedFields }. Emitted when an executor event's free-text fields matched a generic secret pattern and were redacted before storage.

Agents and the execution plane​

These events cover the native TokenTimer agent (as opposed to the external executor path above).

  • CERTOPS_AGENT_BOOTSTRAP_TOKEN_CREATED metadata: { bootstrap_token_id, token_prefix, name, status, expires_at }. Emitted when an admin mints a single-use ttboot_ token to enroll an agent. The token value itself is never in the audit trail, only its prefix.
  • CERTOPS_AGENT_BOOTSTRAP_TOKEN_REVOKED metadata: { bootstrap_token_id, token_prefix, name, status, revoked_at }. Note that a successful enrollment consumes the token rather than revoking it, so a used token produces no separate event; look for the agent's own registration instead.
  • CERTOPS_AGENT_RETIRED metadata: { agentId, force, reason, leasedJobs }, plus { cancelledJobIds, orphanedJobIds } when the retirement fenced in-flight work. A forced retirement (force: true) is the case worth reviewing: orphanedJobIds lists jobs whose real-world effect is unknown because the agent was removed mid-execution, which is the same state described in Reconciling interrupted jobs.
  • CERTOPS_KEY_MATERIAL_REJECTED also fires on the agent routes, with { code: "PRIVATE_KEY_MATERIAL_REJECTED", method, routeFamily: "agent-protocol", agentId } and targetType: "certops_agent". An agent should never send key material, so this event on an agent route means either a misbuilt custom client or a tampered agent. It is written with no actor user, since the caller is a machine.

Approval gates​

  • CERTOPS_JOB_APPROVAL_GRANTED metadata: { jobId, status, payloadHash, canonicalIntentHash }. The two hashes are what the approval is bound to: if the job payload is edited afterwards, the hashes no longer match and the approval is invalidated rather than silently covering the new intent. The actor on this event is the approver, who cannot be the requester.
  • CERTOPS_JOB_APPROVAL_REJECTED metadata: { jobId, status }.

See Approval gates for the rules these events record.

Kill switch​

  • CERTOPS_WORKSPACE_PAUSED / CERTOPS_WORKSPACE_RESUMED metadata: { workspaceId, previousCertOpsPaused, certOpsPaused, certOpsEnabled, certOpsActive, reason }. certOpsEnabled reflects the platform-wide flag and certOpsActive the combination of both, so a pause recorded while the platform flag is off shows certOpsActive: false. reason is operator-supplied free text.

Kubernetes controller​

  • CERTOPS_CONTROLLER_OBSERVATION_ACCEPTED metadata: { apiTokenId, clusterId, managedCertificateId, observationId, resourceRecreated, targetId, certificateInstanceId }. Emitted for each accepted cert-manager observation. resourceRecreated is true when the cluster resource was deleted and recreated under the same identity, which is a legitimate but notable cluster-side change.
  • CERTOPS_CONTROLLER_PROVISION_INTENT_CREATED metadata: { clusterId, jobId, managedCertificateId, targetId }. Emitted when a provisioning intent is authorized, before the controller mutates anything in the cluster. Provisioning is re-authorized before every mutation, so this is the record of intent, not of completion.
  • CERTOPS_GENERIC_SECRET_REDACTION_APPLIED is also emitted against targetType: "certops_controller_observation" when an observation's free-text fields were redacted.

Signing-key rotation​

  • CERTOPS_SIGNING_KEY_ROTATION_STARTED metadata: { signing_key_id, supersedes_signing_key_id, source }.
  • CERTOPS_SIGNING_KEY_ROTATION_COMPLETED metadata: { retired_signing_key_id, active_signing_key_id, forced, force_reason, active_agents, ack_count, source }. A forced: true completion retired the old key before every agent acknowledged the new one, and force_reason records the operator's stated justification.
Deployment-scoped, not workspace-scoped

The job-signing key belongs to the deployment, not to a workspace, so these two events are written with no workspace and no actor user (source: "certops-rotate-signing-key" identifies the CLI). Workspace-scoped and personal audit views filter by workspace or subject user and therefore will not list them; query the audit_events table directly, or use the organization-wide view as a system admin. See Rotate the job-signing key.

See Connect an external executor for how machine API tokens and executor events are used in practice.

Endpoint Monitoring​

  • DOMAIN_MONITOR_CREATED metadata: { url, ssl_detected }
  • DOMAIN_MONITOR_UPDATED metadata: { url, fields_updated }
  • DOMAIN_MONITOR_DELETED metadata: { url }
  • DOMAIN_MONITOR_HEALTH_CHECK metadata: { url, status, response_ms }

Domain Checker​

Emitted when a workspace member discovers publicly known subdomains for a root domain using passive discovery (subfinder), or imports selected hostnames into the workspace as SSL tokens. Lookup is rate limited per workspace and user.

  • DOMAIN_CHECKER_LOOKUP metadata: { domain, source, results, partial, tools_succeeded, tools_failed, truncated }. "source" is "subfinder". "partial" is true when only some discovery tools completed. "tools_failed" lists any tool names that timed out or errored.
  • DOMAIN_CHECKER_IMPORT metadata: { domain, source, submitted, imported, skipped, skipped_duplicate, skipped_invalid, skipped_unreachable, skipped_other_invalid, create_monitors, monitors_created, monitors_existing }. When "create_monitors" is true the event also includes { monitor_check_interval, monitor_health_check_enabled, monitor_alert_after_failures, monitor_contact_group_id }. "submitted" is the number of certificates the client selected, "imported" counts newly created SSL tokens, "skipped_unreachable" counts DNS failures (no name or temporary resolver failure), "skipped_other_invalid" is invalid skips excluding those DNS cases, and "skipped_duplicate" / "skipped_invalid" are aggregate skip counts.