Access Trace

Overview

The Access Trace API provides audit logs and statistics for permission checks performed within applications. Track which users attempted to access which resources and whether access was allowed or denied.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/access-trace`	List access traces
GET	`/api/admin/access-trace/:id`	Get access trace details
GET	`/api/admin/access-trace/stats`	Get access trace statistics
GET	`/api/admin/access-trace/timeline`	Get timeline data

List Access Traces

Retrieve permission check history.

Endpoint

GET /api/admin/access-trace

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 50, max: 100)
`cursor`	string	-	Pagination cursor
`user_id`	string	-	Filter by user ID
`resource`	string	-	Filter by resource
`action`	string	-	Filter by action
`decision`	string	-	Filter by decision (`allow`, `deny`)
`start_date`	string	-	Start date (ISO 8601 format)
`end_date`	string	-	End date (ISO 8601 format)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/access-trace?decision=deny&limit=20" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "trace_abc123",
      "timestamp": "2024-01-22T10:30:00Z",
      "user_id": "usr_xyz789",
      "user_email": "[email protected]",
      "resource": "documents:report_2024",
      "action": "write",
      "decision": "deny",
      "reason": "Insufficient permissions",
      "client_id": "client_app001",
      "ip_address": "203.0.113.1",
      "duration_ms": 5
    },
    {
      "id": "trace_def456",
      "timestamp": "2024-01-22T10:25:00Z",
      "user_id": "usr_abc123",
      "user_email": "[email protected]",
      "resource": "settings:security",
      "action": "read",
      "decision": "allow",
      "client_id": "client_app001",
      "ip_address": "203.0.113.2",
      "duration_ms": 3
    }
  ],
  "total": 1500,
  "cursor": "eyJpZCI6InRyYWNlX2RlZjQ1NiJ9"
}

Get Access Trace Details

Retrieve detailed information for a specified access trace.

Endpoint

GET /api/admin/access-trace/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Access trace ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/access-trace/trace_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "trace_abc123",
  "timestamp": "2024-01-22T10:30:00Z",
  "user": {
    "id": "usr_xyz789",
    "email": "[email protected]",
    "name": "John Doe",
    "roles": ["viewer"]
  },
  "resource": "documents:report_2024",
  "action": "write",
  "decision": "deny",
  "reason": "Insufficient permissions",
  "evaluation": {
    "type": "rbac",
    "checked_permissions": ["documents:write"],
    "user_permissions": ["documents:read"],
    "missing_permissions": ["documents:write"]
  },
  "policies_evaluated": [
    {
      "id": "policy_default",
      "name": "default-viewer-policy",
      "effect": "allow",
      "matched": false,
      "reason": "Action 'write' not in allowed actions"
    }
  ],
  "context": {
    "client_id": "client_app001",
    "client_name": "My App",
    "ip_address": "203.0.113.1",
    "user_agent": "Mozilla/5.0...",
    "session_id": "sess_xyz789",
    "request_id": "req_abc123"
  },
  "duration_ms": 5
}

Get Access Trace Statistics

Retrieve statistics for access checks.

Endpoint

GET /api/admin/access-trace/stats

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	-	Start date (ISO 8601 format)
`end_date`	string	-	End date (ISO 8601 format)
`group_by`	string	-	Grouping (`user`, `resource`, `action`, `decision`)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/access-trace/stats?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "summary": {
    "total_checks": 125000,
    "allowed": 120000,
    "denied": 5000,
    "allow_rate": 96.0,
    "avg_duration_ms": 4.5
  },
  "by_decision": {
    "allow": 120000,
    "deny": 5000
  },
  "by_resource": [
    {
      "resource": "documents:*",
      "total": 50000,
      "allowed": 48000,
      "denied": 2000
    },
    {
      "resource": "settings:*",
      "total": 30000,
      "allowed": 29500,
      "denied": 500
    }
  ],
  "by_action": [
    {
      "action": "read",
      "total": 80000,
      "allowed": 79000,
      "denied": 1000
    },
    {
      "action": "write",
      "total": 35000,
      "allowed": 32000,
      "denied": 3000
    }
  ],
  "top_denied_users": [
    {
      "user_id": "usr_xyz789",
      "user_email": "[email protected]",
      "denied_count": 500
    }
  ],
  "top_denied_resources": [
    {
      "resource": "admin:settings",
      "denied_count": 1500
    }
  ]
}

Get Timeline Data

Retrieve time-series access check data (for chart visualization).

Endpoint

GET /api/admin/access-trace/timeline

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	✓	Start date (ISO 8601 format)
`end_date`	string	✓	End date (ISO 8601 format)
`interval`	string	-	Interval (`hour`, `day`, `week`, default: `day`)
`decision`	string	-	Filter by decision

Request Example

curl -X GET "https://{tenant-domain}/api/admin/access-trace/timeline?start_date=2024-01-15&end_date=2024-01-22&interval=day" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "interval": "day",
  "data": [
    {
      "timestamp": "2024-01-15T00:00:00Z",
      "total": 18000,
      "allowed": 17500,
      "denied": 500,
      "avg_duration_ms": 4.2
    },
    {
      "timestamp": "2024-01-16T00:00:00Z",
      "total": 19500,
      "allowed": 19000,
      "denied": 500,
      "avg_duration_ms": 4.5
    },
    {
      "timestamp": "2024-01-17T00:00:00Z",
      "total": 17000,
      "allowed": 16200,
      "denied": 800,
      "avg_duration_ms": 4.8
    },
    {
      "timestamp": "2024-01-18T00:00:00Z",
      "total": 20000,
      "allowed": 19500,
      "denied": 500,
      "avg_duration_ms": 4.3
    },
    {
      "timestamp": "2024-01-19T00:00:00Z",
      "total": 12000,
      "allowed": 11800,
      "denied": 200,
      "avg_duration_ms": 3.9
    },
    {
      "timestamp": "2024-01-20T00:00:00Z",
      "total": 8000,
      "allowed": 7900,
      "denied": 100,
      "avg_duration_ms": 3.5
    },
    {
      "timestamp": "2024-01-21T00:00:00Z",
      "total": 10000,
      "allowed": 9800,
      "denied": 200,
      "avg_duration_ms": 3.7
    },
    {
      "timestamp": "2024-01-22T00:00:00Z",
      "total": 21000,
      "allowed": 20300,
      "denied": 700,
      "avg_duration_ms": 4.6
    }
  ]
}

Use Cases

Security Monitoring

Monitor denied access to detect unauthorized access attempts.

# Get denied access in the last hour
curl -X GET "https://{tenant-domain}/api/admin/access-trace?decision=deny&start_date=$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)" \
  -H "Authorization: Bearer {token}"

Permission Optimization

Identify frequently denied resources and review permissions as needed.

# Check most denied resources from statistics
curl -X GET "https://{tenant-domain}/api/admin/access-trace/stats?group_by=resource" \
  -H "Authorization: Bearer {token}"

Performance Analysis

Monitor permission check response times and identify bottlenecks.

# Check response time trends in timeline
curl -X GET "https://{tenant-domain}/api/admin/access-trace/timeline?start_date=2024-01-01&end_date=2024-01-31&interval=day" \
  -H "Authorization: Bearer {token}"

Data Retention

Access trace data is retained according to the tenant’s data retention policy. The default retention period is 30 days. You can modify the retention period via the Compliance API.