site/docs/enterprise/audit-logging.md
Audit Logging is a feature of Promptfoo Enterprise that provides forensic access information at the organization level, user level, team level, and service account level.
Audit Logging answers "who, when, and what" questions about promptfoo resources. These answers can help you evaluate the security of your organization, and they can provide information that you need to satisfy audit and compliance requirements.
Audit Logging captures administrative operations within the promptfoo platform. The system tracks changes to users, teams, roles, permissions, and service accounts within your organization.
Please note that Audit Logging captures operations in the promptfoo control plane and administrative actions. Evaluation runs, prompt testing, and other data plane operations are tracked separately.
The following list specifies the supported events and their corresponding actions:
login - Tracks when users successfully authenticate to the platformuser_added - Records when new users are invited or added to the organizationuser_removed - Logs when users are removed from the organizationrole_created - Captures creation of new custom rolesrole_updated - Records changes to existing role permissionsrole_deleted - Logs deletion of custom rolesteam_created - Records creation of new teamsteam_deleted - Logs team deletionuser_added_to_team - Tracks when users join teamsuser_removed_from_team - Records when users leave teamsuser_role_changed_in_team - Logs role changes within teamsorg_admin_added - Records when system admin permissions are grantedorg_admin_removed - Logs when system admin permissions are revokedservice_account_created - Tracks creation of API service accountsservice_account_deleted - Records deletion of service accountsThe audit log entries are stored in JSON format with the following structure:
{
"id": "unique-log-entry-id",
"description": "Human-readable description of the action",
"actorId": "ID of the user who performed the action",
"actorName": "Name of the user who performed the action",
"actorEmail": "Email of the user who performed the action",
"action": "Machine-readable action identifier",
"actionDisplayName": "Human-readable action name",
"target": "Type of resource that was affected",
"targetId": "ID of the specific resource that was affected",
"metadata": {
// Additional context-specific information
},
"organizationId": "ID of the organization where the action occurred",
"teamId": "ID of the team (if applicable)",
"createdAt": "ISO timestamp when the action was recorded"
}
The system tracks changes to the following resource types:
USER - User accounts and profilesROLE - Custom roles and permissionsTEAM - Team structures and membershipsSERVICE_ACCOUNT - API service accountsORGANIZATION - Organization-level settingsThe following examples show the contents of various audit log entries:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"description": "[email protected] logged in",
"actorId": "user-123",
"actorName": "John Doe",
"actorEmail": "[email protected]",
"action": "login",
"actionDisplayName": "User Login",
"target": "USER",
"targetId": "user-123",
"metadata": null,
"organizationId": "org-456",
"teamId": null,
"createdAt": "2023-11-08T08:06:40Z"
}
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"description": "[email protected] created team Engineering",
"actorId": "user-789",
"actorName": "Jane Smith",
"actorEmail": "[email protected]",
"action": "team_created",
"actionDisplayName": "Team Created",
"target": "TEAM",
"targetId": "team-101",
"metadata": null,
"organizationId": "org-456",
"teamId": "team-101",
"createdAt": "2023-11-08T09:15:22Z"
}
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"description": "[email protected] updated role Developer",
"actorId": "user-456",
"actorName": "Admin User",
"actorEmail": "[email protected]",
"action": "role_updated",
"actionDisplayName": "Role Updated",
"target": "ROLE",
"targetId": "role-202",
"metadata": {
"input": {
"permissions": ["read", "write"],
"description": "Updated developer permissions"
}
},
"organizationId": "org-456",
"teamId": null,
"createdAt": "2023-11-08T10:30:15Z"
}
Audit logs are accessible through the promptfoo API. For complete API documentation, see the API Reference.
GET /api/v1/audit-logs
limit (optional): Number of logs to return (1-100, default: 20)offset (optional): Number of logs to skip for pagination (default: 0)createdAtGte (optional): Filter logs created after this ISO timestampcreatedAtLte (optional): Filter logs created before this ISO timestampaction (optional): Filter by specific action typetarget (optional): Filter by specific target typeactorId (optional): Filter by specific user who performed the actionAudit log access requires:
curl -X GET \
"https://your-promptfoo-domain.com/api/v1/audit-logs?limit=50&action=login" \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"total": 150,
"limit": 50,
"offset": 0,
"logs": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"description": "[email protected] logged in",
"actorId": "user-123",
"actorName": "John Doe",
"actorEmail": "[email protected]",
"action": "login",
"actionDisplayName": "User Login",
"target": "USER",
"targetId": "user-123",
"metadata": null,
"organizationId": "org-456",
"teamId": null,
"createdAt": "2023-11-08T08:06:40Z"
}
// ... more log entries
]
}
Audit logs in promptfoo can help meet various compliance requirements:
If you experience issues accessing audit logs:
For additional support, contact the promptfoo support team with details about your specific use case and any error messages received.