---
name: audit-trail
description: >
  Instructs AI agents how to read the Kyriba audit trail. Provides full
  change history for any Kyriba entity - who changed what, when, and what
  the before/after values were.
version: 1.0.0
scopes:
  - audit-trail-scope
authors:
  - kyriba
tags:
  - kyriba
  - platform
  - audit
  - api
---

> **Auth** — POST {AUTH_BASE_URL}/oauth/token · Basic base64(CLIENT_ID:CLIENT_SECRET) · no scope.
> Use token_type verbatim — do not hardcode `Bearer`. On 401: retry once with the other scheme (`token` vs `Bearer`). On 429: wait Kyriba-Customer-Rate-Limit-Reset.

# Kyriba API Skill: Audit Trail

---

## Required Kyriba Permission

```
audit-trail-scope
```

This is a Kyriba access permission — not an OAuth scope parameter. Do NOT add `scope=` to the token request.

---

## What is the Audit Trail?

Read-only API that exposes the full history of changes to any Kyriba entity. For each change you can retrieve the version list (who changed what and when) and then drill into field-level before/after values for any specific version.

> This API is **read-only**. There are no POST, PUT, or DELETE endpoints.

---

## Base URL

```
https://api.demo.kyriba.com/api/platform/referential/audit-trails/v1
```

---

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/platform/referential/audit-trails/v1/audit-trails/{entityType}/{ref}` | List audit trail entries |
| `GET` | `/api/platform/referential/audit-trails/v1/audit-trails/{entityType}/{ref}/{version}/changes` | Get field-level changes for a version |
| `GET` | `/api/platform/referential/audit-trails/v1/audit-trails/documented-fields` | List documented field names |
| `GET` | `/api/platform/referential/audit-trails/v1/audit-trails/documented-fields/{field}` | Get valid enum values |
| `GET` | `/api/platform/referential/audit-trails/v1/audit-trails/searchable-fields` | List filterable fields |

### Path Parameters

| Parameter | Description |
|---|---|
| `entityType` | Type of entity (see table below) |
| `ref` | UUID or code of the entity |
| `version` | Integer version number from the audit list |

---

## `entityType` Values

`ACCOUNT` · `ACCOUNT_GROUP` · `BANK` · `BANK_GROUP` · `BRANCH` · `BUDGET_CODE` · `COMPANY` · `COMPANY_GROUP` · `CURRENCY` · `SUPPLIER_SERVICE_ACCESS` · `SUPPLIER_USER` · `THIRDPARTY` · `THIRD_PARTY_CATEGORY` · `USER` · `USER_GROUP` · `WCF_INTEREST_TERM` · `WCF_DOCUMENT`

> Use `GET /audit-trails/documented-fields/entityType` for the authoritative list.

---

## Pagination

Uses flat `offset` / `limit` - **NOT** `page.offset` / `page.limit`.

---

## Filterable Fields

```
version, auditDate, approval.entryApprovalUserChain, user.code, user.uuid
```

---

## Example Requests

**List audit entries for a company:**
```
GET /api/platform/referential/audit-trails/v1/audit-trails/COMPANY/COMP_FR?offset=0&limit=50&sort=-auditDate
```

**GET list response:**
```json
{
  "metadata": {
    "pageLimit": 100,
    "pageOffset": 0,
    "pageResults": 2,
    "numberOfTotalResults": 2
  },
  "results": [ ... ]
}
```
> Response key is always `results`. Stop paginating when `len(results) < pageLimit`.

**Filter by user:**
```
GET /api/platform/referential/audit-trails/v1/audit-trails/THIRDPARTY/SUPPLIER_A?filter=user.code==jsmith
```

**Get field-level changes for version 3:**
```
GET /api/platform/referential/audit-trails/v1/audit-trails/COMPANY/COMP_FR/3/changes
```

---

## Key Response Fields

### Audit list (`/{entityType}/{ref}`)

| Field | Description |
|---|---|
| `version` | Sequential version number - use in `/{version}/changes` |
| `auditDate` | Timestamp of the change (ISO 8601) |
| `action` | `CREATION`, `MODIFICATION`, or `DELETION` |
| `user.code` | User who made the change |
| `user.uuid` | UUID of the user |
| `userType` | Type of user |
| `approval.entryApprovalUserChain` | Approval chain if dual-admin was required |

### Changes detail (`/{version}/changes`)

| Field | Description |
|---|---|
| `results[].field` | Name of the changed field |
| `results[].oldValue` | Value before the change - **not** `previousValue` |
| `results[].newValue` | Value after the change |

---

##  Common Mistake

| Wrong | Correct |
|---|---|
| `results[].previousValue` | `results[].oldValue` |

---

## Critical Rules

1. `ref` accepts either `uuid` or `code`
2. `version` is an **integer** from the audit list - not a UUID
3. Empty list = no audit trail exists (not a 404)
4. Read-only - no write operations

---

## Error Reference

| Status | Meaning |
|---|---|
| `200` | Success |
| `400` | Invalid filter |
| `403` | Required Kyriba permission not configured on your API client |
| `404` | Entity type or entity not found |

---

## OpenAPI Spec

- OpenAPI: `https://developer.kyriba.com/static/apis/audit-trail/audit-trail.yaml`