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.

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.

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.

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.