Audit events

Talos emits structured audit events via OpenTelemetry span events for all significant lifecycle operations. Events are attached to the active OTEL span and forwarded to any configured OTEL collector. They are never persisted locally.

Each event carries a set of structured attributes that provide context about the operation, the actor, and the affected resource.

Event types

Constant	Event Name	Description
EventAPIKeyCreated	APIKeyCreated	EventAPIKeyCreated is emitted when an API key is created (issued or imported).
Use the KeyType attribute to distinguish between the two origins.
EventAPIKeyUpdated	APIKeyUpdated	EventAPIKeyUpdated is emitted when an API key's metadata is updated.
EventAPIKeyRevoked	APIKeyRevoked	EventAPIKeyRevoked is emitted when an API key is revoked.
EventAPIKeyRotated	APIKeyRotated	EventAPIKeyRotated is emitted when an API key is rotated.
EventAPIKeyVerified	APIKeyVerified	EventAPIKeyVerified is emitted when an API key is successfully verified.
EventAPIKeyVerificationFailed	APIKeyVerificationFailed	EventAPIKeyVerificationFailed is emitted when an API key verification fails.
EventAPIKeyImportFailed	APIKeyImportFailed	EventAPIKeyImportFailed is emitted when an API key import fails.
EventTokenDerived	TokenDerived	EventTokenDerived is emitted when a session token is derived from an API key.
EventAPIKeyDeleted	APIKeyDeleted	EventAPIKeyDeleted is emitted when an issued API key is permanently deleted.
EventImportedAPIKeyDeleted	ImportedAPIKeyDeleted	EventImportedAPIKeyDeleted is emitted when an imported API key is permanently deleted.

Event attributes

Each event carries the following OTEL span event attributes:

OTEL Key	Struct Field	Type	Required	Description
``	NetworkID	uuid.UUID	Required	AttrNetworkID uses the shared semconv NID key so the analytics pipeline can route by project.
APIKeyID	KeyID	string	Optional	Key identification (present for key-related events)
APIKeyPrefix	Prefix	string	Optional
KeyType	KeyType	string	Optional	Key origin (present for created/rotated events)
Operation	Operation	string	Optional	Operation context
Reason	Reason	string	Optional	Failure reason or additional context
ActorID	ActorID	string	Optional	Actor information (who performed the operation)
Expiry	Expiry	*time.Time	Optional	Key properties (present for create/rotate/update events)
Visibility	Visibility	string	Optional	"public" or "secret"
metadata.	Metadata	map[string]string	Optional	Additional context (varies by event type)

Dynamic metadata attributes

The metadata.* prefix supports arbitrary key-value pairs for event-specific context. Metadata keys are prefixed with metadata. in OTEL attributes. For example, a metadata entry {"token_type": "jwt"} becomes the OTEL attribute metadata.token_type with value jwt.

Metadata is optional and varies by event type. Common metadata keys include:

• token_type — Type of derived token (e.g., jwt, macaroon)
• previous_key_id — ID of the key being replaced during rotation
• import_source — Origin of an imported API key

Emitting events

Events are constructed using the fluent builder pattern:

emitter := events.NewOTELEmitter()
events.New(events.EventAPIKeyCreated).
    WithNetworkID(networkID).
    WithKeyType("issued").
    WithKeyID(keyID).
    WithPrefix("talos").
    WithActor(actorID).
    Emit(ctx, emitter)

Events are attached to the active OpenTelemetry span. If no span is recording, the event is silently dropped.