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 result.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.id

String

N/A

Immutable

Identifier (UUID) for 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

String

N/A

Immutable

A string 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.