Action guide

Prove who had what role, at what time

POST/v1/events · admin.role.changed

Emit an `admin.role.changed` event every time a staff member updates a user's or a team member's role. Keep the from/to role names as metadata.

Start logging for freeOpen the playground
When to emit

After the role row is updated in your DB, before notifying the affected user.

Example payload
await recalled.events.create({
  action: "admin.role.changed",
  actor: { id: user.id, email: user.email },
  organization: user.organizationId,
  metadata: {
    fromRole: "value",
    toRole: "value",
    scope: "value"
  },
});
Metadata to include

Keep metadata flat and consistent across your service so it plays well with search and CSV exports.

KeyPurpose
fromRoleRole before the change
toRoleRole after the change
scopeorganization, project, global
Suggested retention

Keep forever for SOC 2 access management evidence.

Related actions

Log admin user suspensions
admin.user.suspended
Log staff impersonation
admin.impersonation.started