Operator guide for Valet Dedicated 0.10.1
Audit log
Valet records each security decision as one audit event: a sign-in, a permission check on a write, an operator's change to a setting. This page lists every field of an event, the values each field takes, and how to read or forward the log. For where the log lives and its alarms, see Observe.
Where the events go
Each event goes to two places:
- The installation's database. This copy is the record. You read it with
valet-dedicated audit listor the dashboard. - The CloudWatch Logs group
/valet/<name>/audit, one JSON line per event. This copy is for forwarding and long-term storage. The api writes it a moment after the database copy. A failed or slow write to the group never blocks a request or changes the database copy.
Recording cannot be turned off. It adds no wait to a request. The record is best effort: a crash can lose the events queued in the last few seconds.
The event line
Each line is one JSON object. Timestamps are RFC 3339 in UTC. Keys are in
snake case. A field with no value is left out, so test for the key. detail
is always an object.
version
- Type
- number,
1 - Present
- Always
id
- Type
- UUID
- Present
- Always
occurred_at
- Type
- RFC 3339 UTC string
- Present
- Always
actor_kind
- Type
- string; see Actors
- Present
- Always
actor_id
- Type
- UUID
- Present
- When known
actor_email
- Type
- string
- Present
- When known
actor_arn
- Type
- string
- Present
- When known
org_id
- Type
- UUID
- Present
- When the event belongs to an org
permission
- Type
- string; see Permissions
- Present
- Always
target_kind
- Type
- string
- Present
- When known
target_id
- Type
- UUID
- Present
- When known
outcome
- Type
- string; see Outcome and reason
- Present
- Always
reason
- Type
- string
- Present
- When not empty
source_ip
- Type
- string
- Present
- When known
request_id
- Type
- string
- Present
- When known
procedure
- Type
- string, the API procedure called
- Present
- When known
detail
- Type
- object
- Present
- Always
Not every event knows every field. Today most events leave out actor_arn
and source_ip.
Actors
actor_kind names who acted.
| Value | Who |
|---|---|
person | A signed-in person |
agent | An agent acting with its own credential |
operator | An installation operator or superuser, or the operator token |
ci | A GitHub Actions workflow that Valet authorizes to deploy |
anonymous | A visitor with no sign-in |
unknown | A request with no identifiable caller |
The operator token appears as actor_kind operator with the fixed
actor_email operator-token. A ci event carries the verified
repository, workflow, workflow_ref, and ref of the workflow in
detail, when it has them.
Permissions
permission names what the actor tried to do. Two families exist.
Org permissions are spelled <noun>.<action>, such as member.invite,
role.assign, connector.create, release.publish, env_var.set, and
access.public. Each org role holds a fixed set of them. Admins hold every
one; Developers hold the rest. The audit log records the decisions on
permissions that change something. It records no read permission, such as
org.read or log.read. It does record the permissions that reveal a
secret, such as env_var.reveal, and a secret.reveal event when a
response returns secret values. It never records the values.
The org permission nouns are: org, member, role, billing, wallet,
cap, catalog, connector, oauth_client, slack_workspace,
org_channel, mailbox, quarantine, resource, org_env_var,
org_drain, release_policy, checker, release, governance,
design_system, audit_log, skill, service, source, process, log,
drain, env_var, access, access_rule, channel, channel_token,
agent, session, and memory. Actions include read, create,
update, destroy, attach, set, reveal, publish, invite,
remove, and assign. Valet support can send the complete list, with
the role that holds each permission.
Operator permissions are spelled operator.<method>, in snake case, such as
operator.set_setting, operator.set_platform_role, and
operator.suspend_user. They record the calls that the operator token and
operator accounts make to the installation's admin API. They are labels,
not org permissions, and no role grants them. Reads, including
ListSettings and ListAuditEvents, record nothing.
Two session events appear in the log: session.create, when someone signs in
(allow) or a sign-in attempt fails (deny), and session.impersonate,
which records a refused impersonated session. The installation refuses every
impersonated session; see How WorkOS works.
Outcome and reason
outcome is the decision.
| Value | Meaning |
|---|---|
allow | The request was admitted |
deny | The request was refused |
would_deny | The actor lacked the permission, but the org does not enforce roles yet, so the request was admitted |
error | The installation could not read the actor's roles, and refused the request |
An allow row records admission, not success. The request can still fail
after it passes the check. Read the matching service log, by request_id,
to see what happened next.
reason explains a decision that was not an allow. It is permission_not_held
for deny and would_deny, and authorization_read_failed for error. A
refused impersonated session carries impersonation forbidden. It is empty,
and left out, on allow. For operator.* events, text the
operator typed with the change goes in detail.reason, never in reason.
Detail
detail holds identifiers and reviewed, non-secret facts about the change.
Settings events carry the setting's name and the operator's optional
reason, never the value. Four operator calls also record what changed:
SetPlatformRole records role, SetOrgRolesEnforced records enforced,
SetOrgBillingExempt records exempt, and SetOrgRuntimeImage records
image. Source and release download calls record admission only, with no URL
or token.
No token, secret, file content, header, or request body enters detail.
Every string in it is cut at 256 bytes.
A sample line
An operator changes a setting with the operator token. The line is wrapped here for reading; the log holds it on one line.
{"version":1,"id":"01939f2c-7a52-7d3e-9c1b-4e8a6f0b2d11",
"occurred_at":"2026-11-13T16:04:09.512Z","actor_kind":"operator",
"actor_id":"01939f00-0000-7000-8000-6f7065726174",
"actor_email":"operator-token","permission":"operator.set_setting",
"outcome":"allow","request_id":"2f6c0d52-3a3e-4f08-8d4a-5b7e8c1a9e60",
"procedure":"/valet.admin.v1.SettingsService/SetSetting",
"detail":{"name":"runtime.standby_count","reason":"increase standby pool"}}The line has no org_id, target_id, or reason: the setting belongs to
the installation, no target was named, and an allow has no decision reason.
Stability
version is 1. These fields and their meaning are stable: every field in
the table, the values of outcome, and the values of
actor_kind that exist today. The module's audit_retention_days input and
the group name /valet/<name>/audit are stable too.
Valet may add a field, a permission, an actor_kind, or a detail key in
any release. Adding one does not change version. Write a reader that
ignores keys it does not know and values it does not recognize.
Valet removes or renames a field, or changes its meaning, only in a minor
release, and raises version when it does. The release notes announce the
change under a heading for audit events, and the previous shape is listed
there. detail keys are reviewed facts about one permission, not a contract
for every consumer: read them by name and tolerate their absence.
Retention
The module keeps the group's events for audit_retention_days, 400 by
default. Set 0 to keep them forever. Lowering the value deletes older events
when you apply. The input is separate from log_retention_days. See the
reference. The database copy has no retention limit.
Read the log
With the tool
valet-dedicated audit list reads the database copy with the operator token.
It covers every org, newest first.
$VD audit list --since 24h --outcome deny
$VD audit list --actor jo@example.com --permission role.assign --output jsonJSON output is one event per line, in the same shape as the log group, then a
next_page_token line when more events remain. Pass the token back with
--page-token and the same filters. See the
reference for every flag.
In the dashboard
An org Admin opens Team, then Audit log. The page lists the org's
events, newest first, in UTC, and filters by actor, permission, and outcome.
A Developer sees a message that an Admin role is required. The page needs
the audit_log.read permission, which only Admins hold.
In CloudWatch
Read the group with the permissions you already hold on your account. For example, show the denials of the last hour:
aws logs filter-log-events --log-group-name /valet/<name>/audit \
--start-time $(( ($(date +%s) - 3600) * 1000 )) \
--filter-pattern '{ $.outcome = "deny" }'Forward the log
A CloudWatch Logs subscription filter sends every new event to a destination you own. The destination can be a Kinesis Data Stream, a Data Firehose delivery stream, or a Lambda function. Datadog and Splunk both document how to receive from one of these: Datadog's Forwarder Lambda, or a Firehose delivery stream to an HTTP endpoint, and Splunk's Firehose integration. Follow your vendor's guide for the destination and its credentials. This page does not give vendor endpoints.
Create the subscription filter on the audit group. A log group holds at most two subscription filters. With the AWS CLI:
aws logs put-subscription-filter \
--log-group-name /valet/<name>/audit \
--filter-name forward-audit \
--filter-pattern "" \
--destination-arn <destination ARN> \
--role-arn <role for CloudWatch Logs to write to the destination>An empty --filter-pattern sends every event. A Lambda destination takes no
--role-arn; instead, grant CloudWatch Logs permission to invoke the
function. Each delivered record is a compressed batch of the lines, not one
line, so your destination must decompress it.
With Terraform, in your own configuration, create the filter on the group
the module makes. The module has no output for the group; its name is
/valet/<name>/audit, where <name> is the module's name input.
resource "aws_cloudwatch_log_subscription_filter" "audit_forward" {
name = "forward-audit"
log_group_name = "/valet/${var.valet_name}/audit"
filter_pattern = ""
destination_arn = var.audit_destination_arn # Firehose, Kinesis, or Lambda
role_arn = var.audit_destination_role_arn
}Omit role_arn for a Lambda destination, and add an
aws_lambda_permission that lets logs.amazonaws.com invoke the function.
Apply the subscription outside the module, as you apply any other AWS change you own. The module creates the group and sets its retention; it does not manage filters you add. To stop forwarding, delete the filter:
aws logs delete-subscription-filter \
--log-group-name /valet/<name>/audit --filter-name forward-auditForwarding copies events. It does not shorten audit_retention_days. A
forwarded copy needs its own retention in the destination.