The Audit Logs API enables you to record security-relevant events in your application and export them for compliance and analysis purposes.
Create Event
Records an audit log event for an organization.
await workos.auditLogs.createEvent(
'org_01HEZYMVP4E1Q5QFZGS4Z0WM25',
{
action: 'user.login_succeeded',
occurredAt: new Date(),
actor: {
id: 'user_01HEZYMVP4E1Q5QFZGS4Z0WM25',
name: 'Jane Doe',
type: 'user',
metadata: {
role: 'admin'
}
},
targets: [
{
id: 'resource_123',
name: 'Production Database',
type: 'database'
}
],
context: {
location: '192.168.1.1',
userAgent: 'Mozilla/5.0'
},
metadata: {
success: true,
method: 'password'
}
},
{
idempotencyKey: 'unique-event-key-123'
}
);
Parameters
The ID of the organization to create the audit log event for.
The audit log event details.
The action that was performed (e.g., user.login_succeeded, document.deleted).
The timestamp when the event occurred.
The entity that performed the action.
Unique identifier for the actor.
Human-readable name of the actor.
The type of actor (e.g., user, system, api_key).
metadata
Record<string, string | number | boolean>
Additional metadata about the actor.
The resources that were affected by the action.
Unique identifier for the target.
Human-readable name of the target.
The type of target (e.g., document, user, organization).
metadata
Record<string, string | number | boolean>
Additional metadata about the target.
Contextual information about where and how the action occurred.
IP address or location identifier where the event occurred.
User agent string of the client that triggered the event.
Schema version number for this action type. Defaults to 1.
metadata
Record<string, string | number | boolean>
Additional custom metadata for the event.
Request options.
Unique key to prevent duplicate event creation. Auto-generated if not provided.
Response
Returns a Promise that resolves to void when the event is successfully created.
Create Export
Creates an export of audit log events matching the specified criteria.
const auditLogExport = await workos.auditLogs.createExport({
organizationId: 'org_01HEZYMVP4E1Q5QFZGS4Z0WM25',
rangeStart: new Date('2024-01-01'),
rangeEnd: new Date('2024-01-31'),
actions: ['user.login_succeeded', 'user.login_failed'],
actorNames: ['Jane Doe'],
actorIds: ['user_01HEZYMVP4E1Q5QFZGS4Z0WM25'],
targets: ['database']
});
Parameters
The ID of the organization to export audit logs for.
Start date for the export range.
End date for the export range.
Filter by specific action types.
Response
Unique identifier for the export.
Current state of the export: pending, ready, or error.
Download URL for the export. Available when state is ready.
ISO 8601 timestamp when the export was created.
ISO 8601 timestamp when the export was last updated.
Get Export
Retrieves the status and details of an audit log export.
const auditLogExport = await workos.auditLogs.getExport(
'audit_log_export_01HEZYMVP4E1Q5QFZGS4Z0WM25'
);
if (auditLogExport.state === 'ready') {
console.log('Download URL:', auditLogExport.url);
}
Parameters
The ID of the audit log export to retrieve.
Response
Unique identifier for the export.
Current state of the export: pending, ready, or error.
Download URL for the export. Available when state is ready.
ISO 8601 timestamp when the export was created.
ISO 8601 timestamp when the export was last updated.
Create Schema
Defines a schema for an audit log action type to validate event structure.
const schema = await workos.auditLogs.createSchema(
{
action: 'document.shared',
targets: [
{
type: 'document',
metadata: {
file_size: { type: 'number' },
encrypted: { type: 'boolean' }
}
},
{
type: 'user'
}
],
actor: {
metadata: {
department: { type: 'string' }
}
},
metadata: {
share_type: { type: 'string' },
expiration_days: { type: 'number' }
}
},
{
idempotencyKey: 'schema-creation-key-123'
}
);
Parameters
The action name this schema applies to.
Schema definitions for target resources.Show target schema properties
The type of target resource.
Schema for target metadata fields. Each key should have a type property with value string, number, or boolean.
Schema definition for the actor.Show actor schema properties
Schema for actor metadata fields.
Schema for event-level metadata fields.
Request options.
Unique key to prevent duplicate schema creation.
Response
Version number of the schema.
Array of target schema definitions.
Event-level metadata schema definition.
ISO 8601 timestamp when the schema was created.