--- title: "GET | List the audit trail of a credential" slug: "api-v2-get-credential-audit-trail" updated: 2026-11-03T14:47:50Z published: 2026-11-03T14:47:50Z canonical: "docs.senhasegura.io/api-v2-get-credential-audit-trail" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt > Use this file to discover all available pages before exploring further. # GET | List the audit trail of a credential ## Description Retrieve every recorded event for a single credential in **PAM Core**, using the v2 canonical model. The response aggregates sessions, rotations, custody releases and configuration changes into one chronological list. The endpoint answers a single question: what happened to this credential. Without it, an auditor cross-references the sessions, rotations and custody resources by hand. This endpoint is part of the **A2A** API v2 surface, introduced in version 4.2.13. No v1 equivalent exists. The v1 API never exposed a per-credential audit trail as a first-class resource. Warning Accesses made through the legacy v1 API do not appear in this trail. The v1 API records them in a separate store that the v2 API cannot reach in this version. --- ## Prerequisites This endpoint uses the same **A2A** authorization as `GET /api/v2/pam/credentials`. In that authorization, the administrator must enable: - **PAM Core** as an authorized resource, with **read** permission. - **Credentials and devices**. - **PAM sessions (V2)**. For more information, access [How to manage authorizations in A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a). --- ## Request `GET` `/api/v2/pam/credentials/{id}/audit-trail` ### Path parameters | Field | Type | Description | | --- | --- | --- | | `id` | string | Unique identification code of the credential whose trail you want to read. | ### Query parameters All query parameters are optional. #### Date range | Field | Type | Description | | --- | --- | --- | | `occurred_at_gte` | string | Returns events that occurred at or after this instant. | | `occurred_at_lte` | string | Returns events that occurred at or before this instant. | #### Sorting `sort_by` accepts a field in the format `field:asc` or `field:desc`. Default direction is `asc`. Example: `sort_by=occurred_at:desc`. For full sorting rules, see [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors). #### Pagination `limit` sets the maximum number of events returned. | Field | Type | Description | | --- | --- | --- | | `limit` | integer | Maximum number of events returned. | This endpoint follows the pagination model shared by the API v2 surface. For the full rules, see [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors). --- ### Example request `GET` `{{url}}/api/v2/pam/credentials/102/audit-trail?limit=4&sort_by=occurred_at:desc` --- ## Response ``` HTTP/1.1 200 OK ``` ### Example response body ``` { "data": [ { "id": "coss_sessao:385", "occurred_at": "2026-08-25T15:19:57-03:00", "event_type": "session_start", "actor": { "id": 134, "username": "_a2a_alice", "name": "alice" }, "outcome": "permitted", "details": {}, "links": { "session": "/api/v2/pam/sessions/399" } }, { "id": "coat_trail:2638", "occurred_at": "2026-08-25T15:18:11-03:00", "event_type": "rotation", "actor": { "id": 134, "username": "_a2a_alice", "name": "alice" }, "outcome": "succeeded", "details": { "attempts": 1 }, "links": { "job": "/api/v2/pam/jobs/45" } }, { "id": "coac_log:642", "occurred_at": "2026-08-25T15:17:03-03:00", "event_type": "configuration_change", "actor": { "id": 134, "username": "_a2a_alice", "name": "alice" }, "outcome": "succeeded", "details": { "action": "Credential rotation requested", "origin": "PAM API", "changed": true } }, { "id": "coac_log:640", "occurred_at": "2026-08-25T14:02:44-03:00", "event_type": "password_view", "actor": { "id": 134, "username": "_a2a_alice", "name": "alice" }, "outcome": "denied", "details": {} } ], "meta": {} } ``` --- ## Response body fields | Field | Type | Description | | --- | --- | --- | | `data` | array of objects | Events recorded for the credential, matching the request filters. | | `data[].id` | string | Unique identification code of the event. | | `data[].occurred_at` | string | Instant when the event occurred. | | `data[].event_type` | string | Type of event. See the following section for the full list. | | `data[].actor` | object | User or application that produced the event. | | `data[].actor.id` | integer | Unique identification code of the actor. | | `data[].actor.username` | string | Username of the actor. | | `data[].actor.name` | string | Display name of the actor. | | `data[].outcome` | string | Result of the event. Possible values depend on the event type. See the following section. | | `data[].source_ip` | string | IP address that originated the event. | | `data[].details` | object | Additional attributes of the event. The fields change according to `event_type`. | | `data[].links` | object | Links to the full source resource of the event. Returned only for event types that have a navigable source. | | `data[].links.session` | string | Path to the session that originated the event. Returned for `session_start`. | | `data[].links.job` | string | Path to the rotation job that originated the event. Returned for `rotation`. | | `meta` | object | Response metadata. | ### Event types The trail aggregates the following event types. | `event_type` | Meaning | `outcome` values | `links` | | --- | --- | --- | --- | | `session_start` | A session was opened against the credential. | `permitted`, `denied` | `links.session` | | `rotation` | The credential password was rotated. | `succeeded`, `failed` | `links.job` | | `configuration_change` | A setting of the credential was changed. | `succeeded`, `failed` | none | | `custody_release` | Custody of the credential was released. | `succeeded`, `failed` | none | | `password_view` | The credential password was viewed. | `permitted`, `denied` | none | | `credential_created` | The credential was created. | `succeeded`, `failed` | none | | `credential_updated` | The credential was edited. | `succeeded`, `failed` | none | > **Note:** Configuration changes do not produce one event type per action. Creating, editing, activating and deactivating a credential all arrive as `configuration_change`, and the action performed is described in `details.action`. ### Details by event type The `details` object changes shape according to `event_type`. #### `rotation` | Field | Type | Description | | --- | --- | --- | | `attempts` | integer | Number of rotation attempts made by the job. | #### `configuration_change` | Field | Type | Description | | --- | --- | --- | | `action` | string | Description of the change performed. Example: `Credential rotation requested`. | | `origin` | string | Origin of the change. Example: `PAM API`. | | `changed` | boolean | Indicates whether the change altered the credential. | --- ## Errors | HTTP code | Message | Possible cause | Solution | | --- | --- | --- | --- | | `401` | `Unauthorized` | Missing or invalid authentication token. | Check the access token and request a new one if expired. | | `403` | `Forbidden` | The authorization does not have read permission to **PAM Core** resources. | Ask the administrator to check the authorization permissions in **A2A**. | | `500` | `Unexpected error.` | Internal server error. | Contact the Segura™ support team. | For the error format, authentication error messages and the `403` versus `404` policy, see [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors). --- ## Related documents - [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors) - [GET | List a credential by id (v2)](/v4-2/docs/api-v2-get-list-a-credential) - [GET | List all credentials (v2)](/v4-2/docs/api-v2-get-list-all-credentials) - [How to manage authorizations in A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a)