Version: 8.2505.x.x RR

Reporting REST API

The following chapter gives an overview of the reporting functionality of the nevisAdapt service through REST API.

There are two potential clients of this API: administrators and end users.

To access the admin endpoints, the user must have the role nevisAdapt.admin assigned.

To access the end user endpoints, the user must have the role nevisAdapt.user and the SecToken must also contain the domain of the user (you can see an example configuration for the SecToken content below).

request:UserId -> userid # same as loginId in admin REST calls
request:Domain -> domain # same as realm in admin REST calls
session:ch.nevis.session.loginid -> loginId
session:ch.adnovum.nevisidm.profileId -> profileId
session:ch.adnovum.nevisidm.clientId -> clientId
request:ActualRoles -> roles

Admin API

The following endpoints are available for the admin users only:

URL: /api/admin/user-observation-groups

HTTP Request Method: GET
Parameters:
- loginId: string
- realm: string
- trustedOnly: boolean (optional)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: JSON content array of UserObservations with pageable metadata

{
  ...
  "content": [{
    uniqueId: string,
    startDate: date,
    endDate: date,
    trusted: boolean,
    type: string,
    cookieName: string,
    cookieValue: string,
    ipAddress: string,
    countryCode: string,
    latitude: decimal,
    longitude: decimal,
    fingerprint: string,
    browserFingerprint: string,
    tlsSessionId: string,
    cypherSuite: string,
    reportCount: long
    },
    ...
   ],
   ...
   "pageable": object,
   ... 
}

Purpose: Fetches the list of all user observations for a given user on admin request.

URL: /api/admin/user-devices

HTTP Request Method: GET
Parameters:
- loginId: string
- realm: string
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: JSON content array of UserDevices with pageable metadata

 {
  "content": [{
    deviceId: long,
    userId: long,
    counter: long,
    firstLogin: date,
    lastLogin: date,
    operatingSystem: string,
    deviceType: string,
    browser: string,
    userAgent: string
    },
  ...
  ],
  ...
  "pageable": object,
  ...
 }

Purpose: Fetches the list of devices of a user on admin request.

URL: /api/admin/session-history

HTTP Request Method: GET
Parameters:
- loginId: string (same as userid in sectoken)
- realm: string (same as domain in sectoken)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: JSON content array of UserSessionDtos with pageable metadata

  {
    ...
    "content": [{
      sessionId: long,
      deviceId: long,
      startDate: date,
      endDate: date,
      operatingSystem: string,
      deviceType: string,
      countryCode: string,
      latitude: decimal,
      longitude: decimal,
      browser: string,
      ipAddress: string,
      trusted: boolean
      },
      ...
    ],
    ...
    "pageable": object,
    ...
  }

Purpose: Fetches the session history for a given user on admin request.

URL: /api/admin/rememberme-tokens

HTTP Request Method: GET
Parameters:
- loginId: string (same as userid in sectoken)
- realm: string (same as domain in sectoken)
- deviceId: integer (optional)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: JSON content array of UserSessionDtos with pageable metadata

  {
    ...
    "content": [{
      deviceId: long,
      clientId: string,
      cookieValue: string,
      loginId: string,
      userExtId: string,
      validUntil: date,
      fingerprint: string
      },
      ...
    ],
    ...
    "pageable": object,
    ...
  }

Purpose: Fetches the rememberme tokens for a given user on admin request.

URL: /api/admin/failed-attempts

HTTP Request Method: GET
Parameters:
- loginId: string (same as userid in sectoken)
- realm: string (same as domain in sectoken)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: JSON content array of RemembermeTokenDtos with pageable metadata

  {
    ...
    "content": [{
      sessionId: long,
      deviceId: long,
      startDate: date,
      endDate: date,
      operatingSystem: string,
      deviceType: string,
      countryCode: string,
      latitude: decimal,
      longitude: decimal,
      browser: string,
      ipAddress: string,
      trusted: boolean,
      },
      ...
    ],
    ...
    "pageable": object,
    ...
  }

Purpose: Fetches the list of all failed attempts for a specific user on admin request.

URL: /api/admin/active-sessions

HTTP Request Method: GET
Parameters:
- loginId: string (same as userid in sectoken)
- realm: string (same as domain in sectoken)
- deviceId: long (optional)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: JSON content array of UserSessionDtos with pageable metadata

  {
    ...
    "content": [{
      sessionId: long,
      deviceId: long,
      startDate: date,
      endDate: date,
      operatingSystem: string,
      deviceType: string,
      countryCode: string,
      latitude: decimal,
      longitude: decimal,
      browser: string,
      ipAddress: string,
      trusted: boolean
      },
      ...
    ],
    ...
    "pageable": object,
    ...
  }

Purpose: Fetches the list of all active sessions for a given user on admin request.

URL: /api/admin/terminateActiveSessions

HTTP Request Method: GET
Parameters:
- loginId: string
- realm: string
Returns: 200 - OK
Purpose: Terminates all active sessions for the given user on admin request.

URL: /api/admin/user-device/{deviceId}/{userId}

HTTP Request Method: DELETE
Path parameters:
- deviceId: long
- userId: long
Returns: 204 - No Content
Purpose: Deletes a device from a user, requested by admin.

URL: /api/admin/rememberme-token/{token}

HTTP Request Method: DELETE
Path parameters:
- token: string
Returns: 204 - No Content
Purpose: Deletes a rememberme token from a user, requested by admin.

End-user API

The following endpoints are available for the end user clients:

URL: /api/user-observation-groups

HTTP Request Method: GET
Parameters:
- trustedOnly: boolean (optional)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: * Returns: See /api/admin/observation-groups

Purpose: Fetches the list of all observations for the calling user.

URL: /api/user-devices

HTTP Request Method: GET
Parameters:
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: See /api/admin/user-devices
Purpose: Fetches the list of devices for the calling user.

URL: /api/session-history

HTTP Request Method: GET
Parameters:
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: See /api/admin/session-history
Purpose: Fetches the session history for a given user on their own request.

URL: /api/risk-event-history

HTTP Request Method: GET
Parameters:
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns:

  {
    ...
    "content": [{
      sessionId: string,
      countryFlag: string,
      countryReputationFlag: string,
      deviceFlag: string,
      deviceSharedFlag: string,
      fingerprintFlag: string,
      browserFingerprintFlag: string,
      fingerprintSharedFlag: string,
      ipAddressFlag: string,
      ipVelocityFlag: string,
      ipSharedFlag: string,
      ipReputationFlag: string,
      riskScore: decimal,
      riskLevel: string,
      created: date,
      sessionEndDate: date
      },
      ...
    ],
    ...
    "pageable": object,
    ...
  }

Purpose: (Demo) Fetches the list of risk calculation results for each login for the calling user.

URL: /api/rememberme-tokens

HTTP Request Method: GET
Parameters:
- deviceId: integer (optional)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: See /api/admin/rememberme-tokens
Purpose: Fetches the rememberme tokens for a given user on admin request.

URL: /api/active-sessions

HTTP Request Method: GET
Parameters:
- deviceId: long (optional)
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: See /api/admin/active-sessions
Purpose: Fetches the list of all active sessions for a given user on their own request.

URL: /api/failed-attempts

HTTP Request Method: GET
Parameters:
- pageable: object
- page: integer (optional)
- size: integer (optional)
- sort: [ [string(,asc|desc)] ] (optional)
Returns: See /api/admin/failed-attempts
Purpose: Fetches the list of all failed attempts for the calling user.

URL: /api/distrustSession

HTTP Request Method: GET
Parameters:
- sessionId: long
Returns: 200 - OK
Purpose: Distrusts observations for the given session.

URL: /api/terminateSession

HTTP Request Method: GET
Parameters: sessionId: long
Returns: 200 - OK
Purpose: Terminates the session inside nevisAdapt immediately. The session is also terminated in Nevis if you configure the nevisAuth reference in the patterns.

URL: /api/user-device/{deviceId}

HTTP Request Method: DELETE
Path parameters:
- deviceId: long
Returns: none
Purpose: Deletes a device from the calling user.

URL: /api/rememberme-token/{token}

HTTP Request Method: DELETE
Path parameters:
- token: string
Returns: 204 - No Content
Purpose: Deletes a rememberme token from the calling user.

URL: /api/rememberme-tokens/{token}

HTTP Request Method: DELETE
Path parameters:
- token: string
Returns: 204 - No Content
Purpose: Deletes all rememberme tokens from the calling user.

Public API

The following endpoints require no authentication as all necessary information is passed in the request parameter and executing the call increases the security for the affected user.

URL: /distrustSession

HTTP Request Method: GET
Parameters:
- feedbackToken: string
Returns: 200 - OK
Purpose: Depending on the action configured inside the feedback token:
- "disabled": nothing happens
- "session": distrusts the observations of this session for the given user
- "device": distrusts the observations of all sessions connected to this device for the given user
- "all": deletes all user observations for the given user

Reporting REST API

Admin API​

URL: /api/admin/user-observation-groups​

URL: /api/admin/user-devices​

URL: /api/admin/session-history​

URL: /api/admin/rememberme-tokens​

URL: /api/admin/failed-attempts​

URL: /api/admin/active-sessions​

URL: /api/admin/terminateActiveSessions​

URL: /api/admin/user-device/{deviceId}/{userId}​

URL: /api/admin/rememberme-token/{token}​

End-user API​

URL: /api/user-observation-groups​

URL: /api/user-devices​

URL: /api/session-history​

URL: /api/risk-event-history​

URL: /api/rememberme-tokens​

URL: /api/active-sessions​

URL: /api/failed-attempts​

URL: /api/distrustSession​

URL: /api/terminateSession​

URL: /api/user-device/{deviceId}​

URL: /api/rememberme-token/{token}​

URL: /api/rememberme-tokens/{token}​

Public API​

URL: /distrustSession​