Audit Logs API

Overview

The Audit Logs API provides comprehensive audit trail capabilities for Digital.ai OKRs, tracking all user actions and system changes. Monitor who made changes, when changes occurred, and what was modified across objectives, key results, sessions, and other OKR entities. This API enables compliance reporting, change tracking, and detailed analysis of user activities within your OKR system.

Every action performed in the Digital.ai OKRs interface—including creates, updates, deletes, and user interactions—is automatically audited and accessible through these endpoints.

Authentication

The Audit Logs API uses the same authentication methods as other Digital.ai Agility APIs:

• Access Tokens (Recommended): Use Bearer token authentication
• Basic Authentication: Username and password
• Windows Integrated Authentication: For domain-authenticated users

Setting Up Authentication

Include the appropriate authentication header with your requests:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

For detailed authentication setup, see API Authentication.

API Endpoints

Get Audit Logs

Retrieve a list of audit log entries with optional filtering and pagination.

GET /okr/audit_logs

Returns basic audit log information including actions, timestamps, and user IDs.

Query Parameters

Parameter	Type	Description	Required
start	integer	Offset of the first fetched item	No
count	integer	Maximum number of fetched items (default: 20, max: 100)	No
sort	string	Sort ordering (default: "id")	No
user_ids	array<string>	Filter by specific user IDs	No
target_entity_id	string	Filter by target entity ID (e.g., specific objective or key result)	No
target_entity_type	string	Filter by entity type (Session, Objective, KeyResult, etc.)	No
base_entity_id	string	Filter by base entity ID (parent entity)	No
id	string	Filter by specific audit log ID	No

Example Request

GET /okr/audit_logs?start=0&count=100&sort=id
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Get Audit Logs with Details

Retrieve audit logs with comprehensive details and enhanced information.

GET /okr/audit_logs/view

This endpoint provides the same filtering capabilities as the basic endpoint but includes detailed information for all entities and changes.

Query Parameters

Same parameters as GET /okr/audit_logs, with identical filtering capabilities.

Example Request

GET /okr/audit_logs/view?target_entity_type=Session&count=50
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Get Single Audit Log

Retrieve detailed information for a specific audit log entry.

GET /okr/audit_logs/{id}

Path Parameters

Parameter	Type	Description	Required
id	string	Unique audit log entry ID	Yes

Create Audit Log Entry

Create a new audit log entry (primarily for testing purposes).

POST /okr/audit_logs

Note: This endpoint is mainly used for testing and internal purposes. Most audit entries are created automatically by the system when users perform actions in the interface.

Response Format

Response Field Descriptions

Pagination Object

Field	Type	Description
count	integer	Number of items returned in current response
next_start	integer	Starting index for next page (null if no more pages)
previous_start	integer	Starting index for previous page (null if on first page)
start	integer	Starting index of current page
total_available	integer	Total number of audit log entries available

Audit Log Entry Object

Field	Type	Description
action	string	Type of action performed (create, update, delete, login, etc.)
base_entity_id	string	ID of the parent entity (null for top-level entities)
changes	array	Array of field changes made during the action
created_dt	string	Timestamp when the audit log entry was created (ISO 8601)
id	string	Unique identifier for the audit log entry
target_entity_id	string	ID of the entity that was acted upon
target_entity_type	string	Type of entity (Session, Objective, KeyResult, User, etc.)
updated_dt	string	Timestamp when the audit log entry was last updated (ISO 8601)
user_id	string	ID of the user who performed the action
user	object	Detailed user information (only in /view endpoint)

Changes Array Object

Field	Type	Description
field	string	Name of the field that was changed
new_value	mixed	New value after the change (null for deletions)
old_value	mixed	Previous value before the change (null for creations)

User Object (in /view endpoint)

Field	Type	Description
created_dt	string	Timestamp when user account was created
email	string	User's email address
external_key	string	External identifier for the user
family_name	string	User's last name
given_name	string	User's first name
id	string	Unique user identifier
name	string	User's full display name
updated_dt	string	Timestamp when user account was last updated

Basic Audit Log Response Structure

{
  "pagination": {
    "count": 20,
    "next_start": 20,
    "previous_start": null,
    "start": 0,
    "total_available": 242
  },
  "results": [
    {
      "action": "create",
      "changes": [
        {
          "field": "id",
          "new_value": "68da5888724d737055984adf",
          "old_value": null
        },
        {
          "field": "begin",
          "new_value": "Wed, 08 Oct 2025 00:00:00 GMT",
          "old_value": null
        },
        {
          "field": "end",
          "new_value": "Tue, 28 Oct 2025 00:00:00 GMT",
          "old_value": null
        },
        {
          "field": "name",
          "new_value": "testing for demo",
          "old_value": null
        }
      ],
      "created_dt": "2025-10-17T14:25:16.597000",
      "id": "68f251cc44b15057a5beb37e",
      "target_entity_id": "68f251cc44b15057a5beb37e",
      "target_entity_type": "Session",
      "updated_dt": "2025-10-17T14:25:16.597000",
      "user_id": "68da5871005b23c01bf21ccd"
    }
  ]
}

Detailed Audit Log Response (with User Details)

{
  "pagination": {
    "count": 20,
    "next_start": null,
    "previous_start": null,
    "start": 0,
    "total_available": 1
  },
  "results": [
    {
      "action": "login",
      "base_entity_id": null,
      "changes": [],
      "created_dt": "2025-10-22T11:36:56.421000",
      "id": "68f8c1d89df32c35a039f7a0",
      "target_entity_id": "68f8367f793810074a29b67e",
      "target_entity_type": "user",
      "updated_dt": "2025-10-22T11:36:56.421000",
      "user": {
        "created_dt": "2025-10-22T01:42:23.901000",
        "email": "john.doe@company.com",
        "external_key": "john.doe@company.com",
        "family_name": "Doe",
        "given_name": "John",
        "id": "68f8367f793810074a29b67e",
        "name": "John Doe",
        "updated_dt": "2025-10-22T01:42:23.901000"
      },
      "user_id": "68f8367f793810074a29b67e"
    }
  ]
}

Single Audit Log Entry Response

When requesting a specific audit log entry by ID, the response contains the individual audit log object without pagination wrapper:

{
  "action": "update",
  "changes": [
    {
      "field": "name",
      "new_value": "testing for demo update",
      "old_value": "testing for demo"
    }
  ],
  "created_dt": "2025-10-17T14:26:04.092000",
  "id": "68f251fc44b15057a5beb37f",
  "target_entity_id": "68f251cc44b15057a5beb37e",
  "target_entity_type": "Session",
  "updated_dt": "2025-10-17T14:26:04.092000",
  "user_id": "68da5871005b23c01bf21ccd"
}

Common Use Cases

Track All Changes to a Specific Entity

Monitor all changes to a particular session, objective, or key result by using the target_entity_id:

GET /okr/audit_logs?target_entity_id=68f251cc44b15057a5beb37e&target_entity_type=Session

Monitor All Activities for an Entity Type

Track all changes across all objectives or sessions by specifying the target_entity_type:

GET /okr/audit_logs/view?target_entity_type=Objective&count=100

View Changes to Child Entities

Track all key result modifications under a specific objective using base_entity_id:

GET /okr/audit_logs?base_entity_id=68fdd97e1fd625dac9b3df&target_entity_type=KeyResult

This shows all key result changes where the base entity (parent objective) matches the specified ID.

User Activity Monitoring

Monitor specific user actions across the system:

GET /okr/audit_logs/view?user_ids=68da5871005b23c01bf21ccd&count=50

Compliance Reporting

Track all system activities over a date range by combining filters:

GET /okr/audit_logs/view?start=0&count=1000&sort=created_dt

System Integration

Integrate audit data with external monitoring or SIEM systems by regularly polling the endpoints and processing the JSON responses.

Understanding Entity Relationships

Target Entity vs Base Entity

• Target Entity: The direct entity being audited (the object that was created, updated, or deleted)
• Base Entity: The parent entity that contains the target entity

Entity Hierarchy Examples

Target Entity Type	Base Entity Type	Description
Session	None	Sessions are top-level entities
Objective	Session	Objectives belong to sessions
KeyResult	Objective	Key results belong to objectives
CustomField	Various	Custom fields can belong to different entity types

Supported Entity Types

Based on the demo, the following entity types are tracked:

• Session: OKR planning sessions
• Objective: Individual objectives within sessions
• KeyResult: Key results associated with objectives
• User: User accounts and authentication
• CustomField: Custom field definitions
• CustomFieldValue: Values for custom fields

Tracked Actions

The audit system captures various action types:

• create: Entity creation
• update: Entity modifications
• delete: Entity removal
• login: User authentication
• archive: Session or objective archival

Error Handling

The API returns standard HTTP status codes:

• 200 OK: Successful request
• 400 Bad Request: Invalid parameters
• 401 Unauthorized: Authentication required
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Audit log entry not found
• 500 Internal Server Error: Server error

Performance Considerations

• Use pagination (start and count parameters) for large result sets
• Filter results using target_entity_type and target_entity_id to reduce response size
• The /view endpoint includes more data but may be slower for large datasets
• Maximum count per request is typically 100 items

Related Topics

• API Authentication
• Bulk API Quick Start
• Email Notifications for OKRs
• Set up API authentication