Action guide
Record every successful login in your audit trail
POST
/v1/events · user.loginEmit a `user.login` event on every successful sign-in. Stores actor, IP, user agent and any MFA method used. Feeds your security dashboards, user timelines and enterprise audit exports.
When to emit
Right after a password or magic link is validated and the session is issued, but before the redirect to the dashboard.
Example payload
await recalled.events.create({
action: "user.login",
actor: { id: user.id, email: user.email },
organization: user.organizationId,
metadata: {
ip: "203.0.113.42",
userAgent: "Mozilla/5.0",
method: "value"
},
});Metadata to include
Keep metadata flat and consistent across your service so it plays well with search and CSV exports.
| Key | Purpose |
|---|---|
ip | Source IP address of the request |
userAgent | User agent string of the client |
method | password, magic-link, sso, oauth, passkey |
mfaUsed | true if a second factor was required |
Suggested retention
Keep for at least 12 months. Enterprise customers often ask for a 1-year login history on request.