Audits API

Overview

The Audits API provides access to comprehensive audit logs that track all actions performed on your Omise account. Use audit logs to monitor user activity, track configuration changes, investigate issues, and maintain compliance records.

Available Endpoints

• Search Audits - GET /audits/search

What You Can Do

• Track User Actions - Monitor all actions performed by users on your account
• Configuration Changes - Track changes to routing groups, rules, and settings
• Activity Timeline - View a chronological history of account activity
• Compliance Auditing - Maintain records for regulatory compliance
• Security Monitoring - Detect and investigate suspicious activity
• Filter by Actor - Find actions performed by specific users

Audit Log Structure

Each audit log entry contains:

Actor Information

• actor_email - Email address of the user who performed the action
• actor_type - Type of actor (e.g., user)

Action Details

• verb - The action performed (e.g., rules_switched)
• created_at - Timestamp when the action occurred

Resource Information

• auditable_type - Type of resource affected (e.g., routing_group)
• auditable_uid - Unique identifier of the affected resource

Searchable Fields

Actor Filters

Filter by who performed actions:

• Email address of the actor
• Type of actor

Action Filters

Filter by what actions were performed:

• Action verb (e.g., rules_switched)
• Date/time range

Resource Filters

Filter by what was affected:

• Resource type
• Resource unique identifier

Use Cases

Find All Actions by a User

GET /audits/search?scope=audit&filters[actor_email][]=admin@example.com

Find Configuration Changes

GET /audits/search?scope=audit&filters[auditable_type]=routing_group

Find Recent Rule Changes

GET /audits/search?scope=audit&filters[verb]=rules_switched&filters[created]=2024/01/01..2024/12/31

Find Actions on a Specific Resource

GET /audits/search?scope=audit&filters[auditable_uid]=rgrp_test_5xuy4w91xqz7d1w9u0t

Example Usage

Search Audit Logs with Filters

const omise = require('omise')({
  secretKey: 'skey_test_...'
});

// Search for routing group changes by a specific user
const results = await omise.search.list({
  scope: 'audit',
  filters: {
    actor_email: ['admin@example.com'],
    auditable_type: 'routing_group',
    created: '2024/01/01..2024/12/31'
  }
});

console.log(`Found ${results.total} audit entries`);
results.data.forEach(audit => {
  console.log(`${audit.created_at}: ${audit.actor_email} - ${audit.verb}`);
});

Python Example

import omise

omise.api_secret = 'skey_test_...'

# Search for all rule switch actions
results = omise.Search.execute(
    scope='audit',
    filters={
        'verb': 'rules_switched',
        'created': '2024/01/01..2024/12/31'
    }
)

print(f'Found {results["total"]} audit entries')
for audit in results['data']:
    print(f'{audit["created_at"]}: {audit["actor_email"]} - {audit["verb"]}')

Response Format

{
  "object": "search",
  "data": [
    {
      "object": "audit",
      "id": "audt_test_5xuy4w91xqz7d1w9u0t",
      "actor_email": "admin@example.com",
      "actor_type": "user",
      "auditable_type": "routing_group",
      "auditable_uid": "rgrp_test_5xuy4w91xqz7d1w9u0t",
      "verb": "rules_switched",
      "created_at": "2024-06-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 30,
  "total_pages": 1,
  "scope": "audit",
  "filters": {
    "actor_email": ["admin@example.com"]
  }
}

Pagination

Audit search results are paginated:

# First page
GET /audits/search?scope=audit&page=1&per_page=30

# Second page
GET /audits/search?scope=audit&page=2&per_page=30

Maximum 100 records per page.

Best Practices

Do This

• Use date filters - Narrow results with created date ranges for better performance
• Filter by actor - Search for specific user actions when investigating issues
• Implement pagination - Handle results in manageable chunks
• Regular auditing - Periodically review audit logs for security monitoring
• Export important logs - Save audit records for long-term compliance

Don't Do This

• Don't skip filtering - Always use filters to narrow results
• Don't ignore errors - Log and handle API errors appropriately
• Don't poll too frequently - Respect rate limits when monitoring

Access Requirements

Audit logs require appropriate account permissions. Contact support if you need access to audit functionality.

Related Resources

• Search Audits - GET /audits/search
• Universal Search - Search across all resources

---

Need help? Contact support@omise.co