Authentications per application


Authentications per application

The authentications per application service calculates the total number of successful sign-on actions for all applications in a specified environment during a specified time 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, see Paging, ordering, and filtering collections.

Filtering data

These SCIM operators can be applied to the following query parameters:

  • ge (greater than or equal to)

    Supported attributes: occurredAt

For more information about SCIM syntax and operators, see Conventions.

Authentications per application API operations

The authentications per application endpoint supports the following operations:

For hands-on experience with the authentications per application API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Authentications per application data model

Property Description
endDate The date and time the authentication data collection ends (ISO 8601 format).
partial A boolean that specifies the partial period. This is an optional property that, when visible in the response data and set to true, indicates that the response represents a shorter duration than requested through the samplePeriod parameter.
signons An integer that represents the number of authentications for the application identified by its application ID between the start and end dates of the sample period.
startDate 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.

Endpoint examples

Get authentications per application

You can get the authentications per application counts for a selected environment over a specified time period. The GET /environments/{environmentId}/applicationSignons request must specify a filter expression that designates a date for the occurredAt attribute. The samplePeriod, and samplePeriodCount query parameters are expected values in the request URL, but they are not part of the filter expression. The limit request parameter is optional and can be omitted.

curl -vX GET "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applicationSignons?limit=2&filter=occurredAt%20ge%20%222019-09-01T19:00:00Z%22&samplePeriod=24&samplePeriodCount=2" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applicationSignons?filter=occurredAt%20ge%20%222019-09-01T19%3A00%3A00Z%22&limit=2&samplePeriod=24&samplePeriodCount=2"
    },
    "next": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applicationSignons?cursor=ewogICJvY2N1cnJlZEF0IiA6ICIyMDE5LTA5LTAxVDE5OjAwOjAwWiIsCiAgInNhbXBsZVBlcmlvZCIgOiAyNCwKICAic2FtcGxlUGVyaW9kQ291bnQiIDogMiwKICAibGltaXQiIDogMiwKICAidG9rZW4iIDogIjAwMWUwMDEwMDAxMjAwMTAzZmEyNzllMjNiOGM0MjdiOWI5MjIxOWVhNTVjOTg5ZmYwN2ZmZmZmZmRmMDdmZmZmZmZkZTQxMWVhOTgzY2Q0NTQyYjg3YjI4YWVmNDkwYWY5NzkwMDA0IiwKICAiY291bnQiIDogMTQKfQ%3D%3D"
    }
  },
  "_embedded": {
    "applications": [
      {
        "id": "3fa279e2-3b8c-427b-9b92-219ea55c989f",
        "authentications": [
          {
            "startDate": "2019-09-01T19:00:00Z",
            "endDate": "2019-09-02T18:59:59Z",
            "signons": 351
          },
          {
            "startDate": "2019-09-02T19:00:00Z",
            "endDate": "2019-09-03T18:59:59Z",
            "signons": 476
          }
        ]
      },
      {
        "id": "1095f42a-2a71-4590-a833-69f5112d95ce",
        "authentications": [
          {
            "startDate": "2019-09-01T19:00:00Z",
            "endDate": "2019-09-02T18:59:59Z",
            "signons": 1256
          },
          {
            "startDate": "2019-09-02T19:00:00Z",
            "endDate": "2019-09-03T18:59:59Z",
            "signons": 1567
          }
        ]
      }
    ]
  },
  "count": 14,
  "size": 2
}

When the endDate in the response is determined to overlap the current date, the partial attribute shows that the response represents a shorter duration than requested by the samplePeriod and samplePeriodCount. The following request shows the partial attribute in the response.

curl -vX GET "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applicationSignons?limit=1&samplePeriod=1&samplePeriodCount=100&filter=occurredAt%20ge%20%222019-10-03T00:00:00Z%22" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applicationSignons?filter=occurredAt%20ge%20%222019-10-03T00%3A00%3A00Z%22&limit=1&samplePeriod=1&samplePeriodCount=100"
    },
    "next": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/applicationSignons?cursor=ewogICJvY2N1cnJlZEF0IiA6ICIyMDE5LTEwLTAzVDAwOjAwOjAwWiIsCiAgInNhbXBsZVBlcmlvZCIgOiAxLAogICJzYW1wbGVQZXJpb2RDb3VudCIgOiAxMDAsCiAgImxpbWl0IiA6IDEsCiAgInRva2VuIiA6ICIwMDFlMDAxMDAwMTIwMDEwMTA5NWY0MmEyYTcxNDU5MGE4MzM2OWY1MTEyZDk1Y2VmMDdmZmZmZmZlZjA3ZmZmZmZmZWQ5NGUxYjM1Y2MyMWI1YjQzYWIxODhmODIzOTNkMjhmMDAwNCIsCiAgImNvdW50IiA6IDE0Cn0%3D"
    }
  },
  "_embedded": {
    "applications": [
      {
        "id": "1095f42a-2a71-4590-a833-69f5112d95ce",
        "authentications": [
          {
            "startDate": "2019-10-03T00:00:00Z",
            "endDate": "120
          },
          {
            "startDate": "2019-10-03T01:00:00Z",
            "endDate": "2019-10-03T01:59:59Z",
            "signons": 40
          },
          {
            "startDate": "2019-10-03T02:00:00Z",
            "endDate": "2019-10-03T02:59:59Z",
            "signons": 35
          },
          {
            "startDate": "2019-10-03T03:00:00Z",
            "endDate": "2019-10-03T03:59:59Z",
            "signons": 145
          },
          {
            "startDate": "2019-10-03T04:00:00Z",
            "endDate": "2019-10-03T04:59:59Z",
            "signons": 211
          },
          {
            "startDate": "2019-10-03T05:00:00Z",
            "endDate": "2019-10-03T05:59:59Z",
            "signons": 54
          },
          {
            "startDate": "2019-10-03T06:00:00Z",
            "endDate": "2019-10-03T06:59:59Z",
            "signons": 34
          },
          {
            "startDate": "2019-10-03T07:00:00Z",
            "endDate": "2019-10-03T07:59:59Z",
            "signons": 68
          },
          {
            "startDate": "2019-10-03T08:00:00Z",
            "endDate": "2019-10-03T08:59:59Z",
            "signons": 87
          },
          {
            "startDate": "2019-10-03T09:00:00Z",
            "endDate": "2019-10-03T09:59:59Z",
            "signons": 71
          },
          {
            "startDate": "2019-10-03T10:00:00Z",
            "endDate": "2019-10-03T10:59:59Z",
            "signons": 66
          },
          {
            "startDate": "2019-10-03T11:00:00Z",
            "endDate": "2019-10-03T11:59:59Z",
            "signons": 96
          },
          {
            "startDate": "2019-10-03T12:00:00Z",
            "endDate": "2019-10-03T12:59:59Z",
            "signons": 39
          },
          {
            "startDate": "2019-10-03T13:00:00Z",
            "endDate": "2019-10-03T13:59:59Z",
            "signons": 88
          },
          {
            "startDate": "2019-10-03T14:00:00Z",
            "endDate": "2019-10-03T14:59:59Z",
            "signons": 57
          },
          {
            "startDate": "2019-10-03T15:00:00Z",
            "endDate": "2019-10-03T15:59:59Z",
            "signons": 79
          },
          {
            "startDate": "2019-10-03T16:00:00Z",
            "endDate": "2019-10-03T16:59:59Z",
            "signons": 99
          },
          {
            "startDate": "2019-10-03T17:00:00Z",
            "endDate": "2019-10-03T17:16:40Z",
            "signons": 55,
            "partial": true
          }
        ]
      }
    ]
  },
  "count": 14,
  "size": 1
}

Query parameter limitations

The following query parameter value ranges are allowed in the request:

Parameter Value range
samplePeriod [1-8760]
samplePeriodCount [1-1000]
limit [1-1000]

In addition, the following product,

samplePeriod * samplePeriodCount * limit

must be less than or equal to 100,000. If one query parameter limitation is violated, the service returns an error with HTTP status code 400.