Record an authentication audit event (FM-494)

POST

/api/v1/me/auth-event

curl --request POST \
  --url http://localhost:3000/api/v1/me/auth-event \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "event": "auth.login.success", "success": true, "provider": "example", "errorCode": "example", "errorDescription": "example", "metadata": {} }'

• Development
• Production

Emits a tamper-evident audit-log entry for an auth-flow event observed by the BFF (login, refresh, logout, federated, session termination). The signing uses the same AUDIT_HMAC_SECRET as the rest of the audit pipeline.

Authorizations

• bearer

Parameters

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Body^required

Media typeapplication/json

object

event

required

Canonical auth-audit event name (FM-494).

string

Allowed values: auth.login.success auth.login.failed auth.refresh.success auth.refresh.failed auth.logout auth.session_terminated_by_admin auth.federated_login.success auth.federated_login.failed

success

required

Whether the underlying auth operation succeeded.

boolean

provider

OAuth/OIDC provider name when relevant (e.g. “keycloak”, “entra”).

string

errorCode

Short error code for failed events (e.g. “expired_token”).

string

errorDescription

Human-readable error description for failed events.

string

metadata

Free-form metadata (small JSON object). MUST NOT contain access tokens.

object

Responses

204

Audit event recorded

400

Invalid payload

401

Unauthorized