Introduction to Audit Logs

Retrieve a record of actions performed in your workspace — who did what, when, and from where.

The Audit Logs API can be used to:

Feed workspace activity data into your SIEM or other monitoring tools
Track changes across your organization, from workspace settings and model configuration to workflows, skill and action access, role changes, failed login attempts, and more
Build custom dashboards and reports for workspace activity

Prerequisites

To use the Audit Logs API, you need:

Workspace Admin Permission: Only workspace administrators can create API keys with audit log permissions.
API Key with AUDIT_LOG_API Scope: Your API key must have the dedicated audit log scope enabled. Create it in Settings > API in your workspace settings.

Retention

Audit log entries are retained for 90 days. Make sure to export or forward any data you need before it expires.

Available Endpoint

GET /audit-logs/{workspace_id}

Authentication

All API requests require Bearer token authentication:

bash

Authorization: Bearer YOUR_API_KEY

The Audit Log Entry

Every audit log entry describes an actor taking an action on an entity. Here's what each entry contains:

Field	Description
`actor_id`, `actor_type`, `actor_name`	Who performed the action. Actor types: `USER`, `API_KEY`, `SYSTEM`, `SCIM`
`action`	What happened, in dot notation (e.g. `user.updated`, `workspace.created`, `model_config.updated`, `workflow.created`, `api_keys.deleted`)
`entity_type`, `entity_id`	Which resource was affected (e.g. `User`, `Workspace`, `Group`, `IntegrationConnection`, `ModelConfig`, `Workflow`, `SkillAccess`, `ActionAccess`)
`created_at`	When the event occurred
`ip_address`, `user_agent`	Where the request came from
`changes`	A `before`/`after` diff of changed fields (for update events)
`snapshot`	Full entity snapshot or additional event metadata (e.g. on delete/create events, or extra context like failed login details)

Pagination

The API uses cursor-based pagination. Each response includes a next_cursor field — pass it as the cursor query parameter in your next request to get the following page. When next_cursor is null, you've reached the end.

bash

# First request
curl "https://api.ajan.io/audit-logs/{workspace_id}?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl "https://api.ajan.io/audit-logs/{workspace_id}?limit=50&cursor={next_cursor}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtering

You can narrow results using query parameters:

Parameter	Type	Description
`from`	`datetime`	Start of date range (ISO 8601)
`to`	`datetime`	End of date range (ISO 8601)
`entity_type`	`string`	Filter by entity type (e.g. `User`, `Workspace`)
`actor_id`	`uuid`	Filter by the actor who performed the action
`limit`	`integer`	Items per page (default 50, max 50)
`cursor`	`uuid`	Cursor from previous response for pagination

Error Handling

Status Code	Description
`400`	Invalid request parameters (e.g. malformed date, invalid UUID)
`401`	Missing or invalid API key
`403`	API key lacks `AUDIT_LOG_API` scope, or `workspace_id` doesn't match
`429`	Rate limit exceeded — back off and retry
`500`	Internal server error