PingOne Platform APIs

Authentications per Application

The authentications per application service calculates the number of successful sign-on actions for all applications in a specified environment during a specified time period. This metric shows how often applications are accessed, using authentications as the measure of the application’s usage. Organizations can use this metric to:

  • Determine which applications are responsible for the highest volume of authentication requests, in rank order.

  • Refer to which applications are rarely used and are candidates for decommission.

  • Refer to the relative number of authentication requests for each connected application.

  • Determine whether an application’s usage is growing or shrinking over time.

  • View the total number of authentication requests per application over time.

The count of successful authentications is the total number of FLOW.UPDATED events with COMPLETED status during the specified period.

For example, suppose you want to see the number of authentications (per application) per day for a three-day period starting on September 1, 2019. Requests to this service require the following filter parameter to define the query:

  • occurredAt

    Specifies the start date for the period of interest. For this example, to specify a date range starting on September 1, 2019, the value is occurredAt ge "2019-09-01T00:00:00Z".

Requests to this service also require the following query parameters to define the query:

  • samplePeriod

    Specifies the time interval in hours. For this example, to specify a daily interval, the value is samplePeriod=24.

  • samplePeriodCount

    Specifies the number of sample periods. For this example, to specify three days of results, the value is samplePeriodCount=3.

The authentications per application service supports limit as an optional query parameter to specify a subset of applications returned in the response. For information about limiting collections, refer to Conventions.

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.

Authentications per application data model

Property Type Required Mutable Description

endDate

Date

Required

Mutable

The date and time the authentication data collection ends (ISO 8601 format).

partial

Boolean

Optional

Mutable

Indicates the partial period. When visible in the response data and set to true, this indicates that the response represents a shorter duration than requested through the samplePeriod parameter.

signons

Integer

Required

Mutable

The number of authentications for the application identified by its application ID between the start and end dates of the sample period.

startDate

Date

Required

Mutable

The date and time the authentication data collection starts (ISO 8601 format).

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.

500

Internal server error.

Authentications per application errors

In addition to the general error codes, authentications per application 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: filter is expected to be specified, samplePeriod is expected to be specified, or samplePeriodCount is expected to be specified

When and details

When: A GET authentications per application request omits the filter, samplePeriod, or samplePeriodCount parameter.

Details: None.

400

INVALID_DATA

None

Message: Filter parameter is wrong. Issue with occurredAt.

When and details

When: A GET authentications per application request specifies an occurredAt filter value that is empty or not a valid date and time.

Details: None.

400

INVALID_DATA

None

Message: Filter parameter is wrong. Issue with start date can not be greater than current date.

When and details

When: A GET authentications per application request specifies an occurredAt filter value that is later than the current date.

Details: None.

400

INVALID_DATA

None

Message: Filter parameter is wrong. Issue with Filter parameter is wrong. Start date can not be earlier than 2 years ago.

When and details

When: A GET authentications per application request specifies an occurredAt filter value that is more than 2 years earlier than the current date.

Details: None.

400

INVALID_DATA

None

Message: samplePeriod is expected to be in range from 1 to 8760 or samplePeriodCount is expected to be in range from 1 to 1000

When and details

When: A GET authentications per application request specifies a samplePeriod value outside the range 1-8760 or a samplePeriodCount value outside the range 1-1000.

Details: None.

400

INVALID_DATA

None

Message: Product of samplePeriod, samplePeriodCount and limit parameters is expected to be less or equal to 100000

When and details

When: The product of the samplePeriod, samplePeriodCount, and limit values exceeds 100000.

Details: None.

400

UNEXPECTED_ERROR

None

Message: Limit parameter should be in (1 - 1000) range.

When and details

When: A GET authentications per application request specifies a limit value outside the range 1-1000.

Details: None. The top‑level code is UNEXPECTED_ERROR (not INVALID_DATA): the LimitValidator violation is not a RequestParametersConstraint, so it falls through to the advice’s fallback errorCode() branch, which maps every other constraint annotation to UNEXPECTED_ERROR with HTTP 400.

400

INVALID_DATA

None

Message: Cursor parameter is wrong. Issue with cursor is null or empty or Cursor parameter is wrong. Issue with deserialization.. (the template appends a period to the reason, which already ends in one)

When and details

When: A GET authentications per application request specifies a cursor that is null or empty, or a cursor that the service cannot deserialize.

Details: None.

400

INVALID_REQUEST

None

Message: Wrong order parameter. Available order parameter is 'signons' or '-signons. (the source message has an unclosed quote)

When and details

When: A GET authentications per application request specifies an order value other than signons or -signons.

Details: None. The top‑level code is INVALID_REQUEST for this handler.

400

INVALID_DATA

None

Message: Invalid UUID string: <environmentId>

When and details

When: A GET authentications per application request specifies an environmentId path value that is not a valid UUID.

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 orgmgt:read:environment permission (GET operation).

Details: None.

500

UNEXPECTED_ERROR

None

Message: Issue with fetching data from data server.

When and details

When: The service fails to fetch data from the data server (an ApplicationSignOnDaoException is raised).

Details: None.