PingOne Platform APIs

Audit Activities

Audit reporting caches incoming audit messages and provides endpoints to request audit events for a specified date range. The /activities endpoint returns all audit log events over the specified period of time. The response shows complete audit entries, and it pages the returned data if the number of entries requires multiple pages.

The /activities endpoint has a lower rate limit than other endpoints, so should not be used for logins or other high-throughput processes. Instead, use Subscriptions API to capture events for these processes.

The following events and actors are tracked:

  • Actions

    Logs any action or activity against a defined PingOne resource. The audit message includes the ID for the resource affected by the event.

  • Actors

    Tracks the actor or agent who initiated the action. The audit message includes the unique identifier and the friendly name of the actor (end user) responsible for the event and the client used by the actor to perform the action on the resource.

  • Date and time

    The date and time the audit activity was recorded.

  • Status

    Tracks and caches the resulting status of the action. The audit message specifies the success or failure of the event, and if a failure occurred, it provides the reason for the failure.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Audit reporting data model

Property Type Required Mutable Description

_embedded

Object

Required

Immutable

A reserved HAL object used to include fully represented service properties.

action

Object

Required

Immutable

Object that contains properties of the action performed.

action.description

String

Required

Immutable

Description of the action performed.

action.type

String

Required

Immutable

Type of action performed (such as authentication or password reset).

actors

Object

Required

Immutable

Object that contains properties of the actors involved in the action.

actors.client.id

String

Required

Immutable

Identifier (UUID) of the client.

actors.client.name

String

Required

Immutable

Name assigned to the client for PingOne sign-on.

actors.client.type

String

Optional

Immutable

Type of actor. Can be USER or CLIENT.

actors.client.href

String

Optional

Immutable

URL for the specified client resource.

actors.client.environment.id

UUID

Required

Immutable

Identifier (UUID) of the environment resource associated with the client.

actors.user.id

UUID

Required

Immutable

Identifier (UUID) of the user.

actors.user.name

String

Required

Immutable

Name assigned to the user for PingOne sign-on.

actors.user.href

String

Optional

Immutable

URL for the specified user resource.

actors.user.population

String

Optional

Immutable

Population of the specified user resource.

actors.user.type

String

Optional

Immutable

Type of actor. Can be USER or CLIENT.

actors.user.environment.id

UUID

Required

Immutable

Identifier (UUID) of the environment resource associated with the user.

actors.user.population.id

UUID

Required

Immutable

Identifier (UUID) of the population resource associated with the user.

correlationId

UUID

Optional

Immutable

PingOne identifier (UUID) for multiple messages in a transaction.

createdAt

Date

Optional

Immutable

Date and time at which the event was created (ISO 8601 format).

id

UUID

Required

Immutable

Identifier (UUID) of the audit activity event.

internalCorrelation.sessionId

UUID

Optional

Immutable

PingOne actor session identifier (UUID).

internalCorrelation.transactionId

String

Optional

Immutable

PingOne transaction identifier (UUID).

externalCorrelation.sessionId

UUID

Optional

Immutable

X-Ping-External-Session-Id header value of the originating HTTP request.

externalCorrelation.transactionId

String

Optional

Immutable

X-Ping-External-Transaction-Id header value of the originating HTTP request.

recordedAt

Date

Required

Immutable

Date and time at which the event was recorded (ISO 8601 format).

resources.href

String

Required

Immutable

URL for the specified resource.

resources

Object

Required

Immutable

Object that contains properties of the resources affected by the action.

resources.davinciId

String

Optional

Immutable

DaVinci native ID, a 32-character lowercase hex string (same bits as a UUID but without dashes). Audit maps it to a UUID for the resources.id property. This preserves the original DaVinci ID for traceability and search.

resources.environment.id

UUID

Required

Immutable

Identifier (UUID) of the environment that the resource belongs to.

resources.id

UUID

Required

Immutable

Identifier (UUID) assigned as the key for the identifier resource (such as the environment, population, or event message).

resources.name

String

Required

Immutable

A string that can be either the user name or the name of the environment, based on the resource type.

resources.type

String

Required

Immutable

Type of resource associated with the event. Can be USER, ORGANIZATION, or ENVIRONMENT.

resources.population.id

UUID

Required

Immutable

Identifier (UUID) assigned as the key for the population resource.

result

Object

Required

Immutable

Object that contains properties of the result of the action.

result.description

String

Optional

Immutable

Description of the result of the operation.

result.reason

String

Optional

Immutable

Reason for the result of the operation.

result.status

String

Optional

Immutable

Result of the operation. Can be succeeded or failed.

source

Object

Required

Immutable

Object that contains properties of the source originating the request.

source.ipAddress

String

Optional

Immutable

IP address of the originating HTTP request.

source.userAgent

String

Optional

Immutable

User-Agent header value of the originating HTTP request.

tags

Object

Required

Immutable

Object that contains properties of tags associated with the activity.

tags.adminIdentityEvent

Object

N/A

Immutable

Array of strings identifying the activity as the action of an administrator on other administrators.

Filtering data

The GET {{apiPath}}/v1/environments/{{envID}}/activities and POST {{apiPath}}/v1/environments/{{envID}}/activities requests accept SCIM filtering expressions to fine-tune the response data. For large collections, additional filtering expressions can be added to the request URL to focus on particular event types.

The minimum filter must include:

  • A date range for the recorded event time.

Filter Description

recordedat lt "yyyy-MM-dd’T’HH:mm:ss.SSSZ"

Audit events recorded before the specified time.

recordedat gt "yyyy-MM-dd’T’HH:mm:ss.SSSZ"

Audit events recorded after the specified time.

For example, this SCIM filter returns audit events from the start date of "2018-01-01" and an end date of "2018-03-31":

https://api.{pingone}.com/v1/environments/{{envID}}/activities?filter=recordedat gt "2018-01-01T00:00:00Z" AND recordedat lt "2018-03-31T23:59:00Z"

The filter can also include any one of the following:

  • Population ID

  • Actor ID and optional population ID.

  • Action Type and optional population ID

  • Resource ID

  • Resource Type and optional population ID

Filter Description

resources.population.id eq ":id"

Audit events associated with the specified population.

actors.user.id eq ":id"

Audit events performed by the specified user ID or client ID. Optionally, you can include the associated population.

action.type

Audit events recorded for the specified type of action (such as, authentication, password reset). Optionally, you can include the associated population.

resources.id eq ":id"

Audit events recorded for the specified resource.

resources.type

Audit events recorded for the specified type of resource. This can be any one of the following: ALL, USER, ENVIRONMENT, ORGANIZATION. Optionally, you can include the associated population.

tags

Audit events for the adminIdentityEvent tag. Currently, the adminIdentityEvent tag is the only one supported.

These SCIM operators can be applied to the following attributes:

  • eq (equals)

    Supported attributes: correlationid, actors.user.id, actors.user.name, actors.client.id, action.type, resources.id, resources.type, resources.population.id, org.id, environment.id

  • gt (greater than)

    Supported attributes: recordedat

  • lt (less than)

    Supported attributes: recordedat

  • ge (greater than or equal to)

    Supported attributes: recordedat

  • le (less than or equal to)

    Supported attributes: recordedat

  • and (logical AND)

    Logical AND for building compound expressions in which both expressions are true.

  • or (logical OR)

    Logical OR for building compound expressions if either expression is true.

These SCIM operators are not supported: ne (not equal), co (contains), ew (ends with), in (includes), pr (present, is a non-empty or non-null value), sw (starts with), not (logical NOT).

For more information about SCIM syntax and operators, refer to Conventions.

Response codes

Code Message

200

Successful operation.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

Audit activity errors

In addition to the general error codes, audit activity operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

None

Message: Invalid Filter: <message> for filter failures, where <message> describes the validation failure (for example, Attribute '<attribute>' is not supported in filter); otherwise The input limit '<limit>' is greater than the allowed maximum limit of <maxLimit>, Illegal argument: limit=<limit>. Limit must be greater than 0, or Invalid Base64 data '<cursor>' encountered when attemting to process offset

When and details

When: A GET or POST Read Audit Activities request specifies a filter that the service cannot evaluate (an unsupported attribute, an unsupported operator for the attribute, a value of the wrong type, an unsupported operator combination, conflicting filter attributes, or a limit greater than the maximum page size), a limit value that is zero, negative, or not a number, or a cursor value that is not valid Base64-encoded data. When a cursor is present, the limit message is prefixed with [Invalid Cursor] followed by a space

Details: None.

400

INVALID_DATA

None

Message: Request cannot be served for the given filter. Narrow the time range and try again.

When and details

When: A GET or POST Read Audit Activities request specifies a query that the service cannot serve for the given filter.

Details: None.

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: The request fails bean validation (for example, a POST Restore Activities request omits the minTimestamp or maxTimestamp property).

Details: must not be null for the omitted property, for example Validation Error : [minTimestamp must not be null].

400

INVALID_DATA

None

Message: The message text varies with the unsupported operation (for example, Unsupported filter: <queries> or Filter combination not supported.)

When and details

When: A request specifies an unsupported operation, such as a query for an attribute combination the service does not support.

Details: None.

401

ACCESS_FAILED

None

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The request omits a valid bearer token, or the actor holds the audit_reporting:read:userActivity permission but the filter does not target only users or authorized populations.

Details: None.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the audit_reporting:read:activity permission for the operation (GET or POST operations).

Details: None.

404

NOT_FOUND

None

Message: No Audit Event Found

When and details

When: A GET Read One Audit Activity request specifies an activityID that does not exist in the specified environment.

Details: None.

500

UNEXPECTED_ERROR

None

Message: Database error: (<message>) for database failures; otherwise the message text varies with the internal error.

When and details

When: The service encounters a database or other internal error while processing the request.

Details: None.