Audit log
Field-level reference for audit events, the action catalog, and the query API.
The audit log records control-plane actions in a namespace: who did what to firewalls, tokens, teams, webhooks, and Trusted Builders, and what was denied. For review workflows, see Review the audit log.
Event shape
{
"id": "01J...",
"createdAt": "2026-07-03T10:22:41Z",
"namespace": "ns-01KYA296JWEE36NDNRTJ4KM82Q",
"action": "firewall.rule.upsert",
"resourceType": "firewall",
"resourceId": "3e7f5cb806f26e3beae2",
"actorUserId": "user-7d2f...",
"actorTokenIdentifier": "5f8a...",
"requestId": "8f4c2e...",
"interactionId": "build-4711",
"remoteAddr": "203.0.113.7",
"userAgent": "bsfw/1.4.0",
"requestMethod": "PUT",
"requestPath": "/v1/ns-01KYA296JWEE36NDNRTJ4KM82Q/config/3e7f5cb806f26e3beae2/rules/delay-14d",
"outcome": "success",
"statusCode": 200,
"eventData": { "rule": "delay-14d" }
}Fields
| Field | Type | Description |
|---|---|---|
id | string | Event ID |
createdAt | string | When the action happened |
namespace | string | Namespace ID the action targeted |
action | string | What was done, see catalog below |
resourceType | string | firewall, token, namespace, session, team, trusted_builder, license_set, webhook |
resourceId | string | The specific resource. For firewalls this is the firewall ID, never the display name; firewalls created in the dashboard get a generated ID that differs from their name, so search by ID |
actorUserId | string | Acting user's ID, when the session belongs to one. An opaque identifier (the token's OIDC subject), not an email or display name; the dashboard resolves it to a name where it can |
actorTokenIdentifier | string | Hash-derived identifier of the acting token. Never contains token material, but is stable, so repeated use of one token is correlatable |
requestId | string | Request ID, shared with firewall log entries from the same request |
interactionId | string | Interaction ID from the token suffix, if any |
remoteAddr, userAgent, requestMethod, requestPath | string | Request metadata. Path excludes the query string |
outcome | string | success or failure |
statusCode | number | HTTP status returned |
errorMessage | string | Short failure reason, on failures |
eventData | object | Action-specific detail, for example the missing permission on a denial or the claim mismatch on an OIDC failure |
Action catalog
| Action | Emitted when |
|---|---|
auth.failed | A request presented a missing or invalid token and its requested namespace could be assigned safely to one tenant |
auth.namespace_denied, authz.namespace_denied | A valid token was used outside its namespace or without namespace access |
authz.denied | An action was attempted without the required permission; eventData.permission names it |
firewall.access | Firewall traffic access was denied per-resource |
firewall.config.upsert, firewall.config.delete, firewall.config.rollback | Configuration imported/changed, firewall deleted, config rolled back |
firewall.rule.upsert, firewall.rule.delete | A rule changed or was removed |
firewall.exception.upsert, firewall.exception.delete | An exception changed or was removed |
firewall.credentials.upsert | Upstream credentials were set or rotated |
license_set.create, license_set.update, license_set.delete | License set management |
namespace.provision, namespace.create, namespace.update, namespace.delete, namespace.clone | Namespace lifecycle; provision is the auto-provisioning on an admin's first login |
token.personal.create, token.service.create, token.delete | Token lifecycle |
team.create, team.update, team.delete, team.member.add, team.member.remove | Team management |
trusted_builder.create, trusted_builder.update, trusted_builder.delete | Trusted Builder management |
webhook.create, webhook.update, webhook.delete, webhook.test, webhook.secret.rotate, webhook.unquarantine | Webhook management. Subscribable as audit.webhook.* webhook events |
oidc.exchange | A Trusted Builder exchange succeeded, or a failed exchange identified a configured builder. Malformed tokens and unknown audiences are not visible in a tenant audit log |
Query API
GET /v1/<namespace-id>/audit| Parameter | Description |
|---|---|
action | Exact action string from the catalog |
resourceType | Resource type |
resourceId | Specific resource |
actorUserId | Acting user's raw ID, not the display name. Copy it from the event detail in the dashboard |
outcome | success or failure |
from, to | RFC 3339 time bounds |
limit | Page size, default 100, maximum 1000 |
offset | Page offset |
The response wraps events with total, limit, and offset for paging.
Related
- How-to: Review the audit log
- Concept: Observability, Access and permissions
- Reference: API, Logs