Audit Records REST API

The AuditRecords endpoint allows managing and searching for events in the secure, tamper-evident audit log maintained of all authentication, administration, and authorization requests.

The audit log entries contain a complete set of data to enable a compliance-oriented view of system activities, including action, system user, end user, channel, date, time, and outcome.

Note: The API version supported by HID Authentication Service is 10.3.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method Entity Action Request URI Description

GET

Read

/scim/{tenant}/v2/AuditRecords

Get Audit Records filtered by attributes
POST

Create

/scim/{tenant}/v2/AuditRecords

Create an audit event
POST

Search

/scim/{tenant}/v2/AuditRecords/.search

Search for an audit event

Required Permissions

Function Required Permissions

GET

Create external audit

POST

For search, Read audit log

Get an Audit Record

As with .search, you can use GET to find an audit record by adding parameters in the query.

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/AuditRecords
Copy

Sample Request

POST /scim/{tenant}/v2/AuditRecords
{
 "filter": "created gt 2022-11-27T12:00:00Z",
 "count": 10,
 "startIndex": 0
}

Create an Audit Record

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/AuditRecords
Copy

Sample Request

POST /scim/{tenant}/v2/AuditRecords
{
    "result": "SUCCESS",
    "service": {
        "name": "my service name"
    },
    "severity": "Alert",
    "action": {
        "actionParameters": {
            "ATC": "AT_SYSLOG"
        },
        "actionName": "primaryAuthenticateUP"
     },
    "targetUserId": {
        "immutableId": 11055
    },
    "correlationId": "myCorrelationId",
    "message": "this message"
}

Where the mandatory fields are:

  • service.name

  • action.actionName

  • severity - possible values are:

    • Information

    • Warning

    • Error

    • Alert

  • result - possible values are:

    • PENDING

    • SUCCESS

    • FAILURE

Note:

  • targetUserId.immutableId - must contain only numerical characters

    The ID can be linked to a user within the HID Authentication Service or a reference for an external system (for example, if using the HID Authentication Service as an auditing service for a third-party system).

  • The following fields cannot be set:

    • targetUserId.id - readonly

    • targetUserId.tenantId - readonly

    • targetUserId.session - readonly

    • actingUserId - will be set with the user making the call

    • jws - the signature will be calculated before database insertion

    • integrityStatus - readonly

    • created - will be set with current date before database insertion

Search for an Audit Record

The supported search criteria that can be used as filters are:

SCIM Attribute Operators supported Case-sensitive Tokenized Wildcard

actingUserId.id

eq

 Yes Yes No

actingUserId.immutableId

eq

 Yes Yes No

actingUserId.session.authenticationMethod

eq, co, sw, ew

 Yes No Yes

action.actionName

eq, co, sw, ew

 Yes No Yes

action.actionParameters.CHC

eq, co, sw, ew

Filters for the channel in the action parameters of the audit record

 Yes No Yes

action.actionParameters.COI

eq, co, sw, ew

Mapped to AuditRecordSearchCriteria.batchCorrelationId and filters for the correlation ID returned in the response (for example, the correlation ID returned for bulk user import)

 Yes No Yes

action.actionParameters.DSN

eq

Filters for the device serial number in the action parameters of the audit record

The exact value should be used

 Yes Yes No

action.actionParameters.text1...text10

eq, co, sw, ew

Filters for custom action parameters

 No No Yes

correlationId

eq, co, sw, ew

Mapped to AuditRecordSearchCriteria.correlationId and filters for the X-Correlation_id header value.

 Yes No Yes

created

gt/lt

(date of creation, timestamp)

 No No No
id eq, co, sw, ew Yes No Yes

result

eq RESPONSE_SUCCESS or RESPONSE_FAILURE

Filters for successful or failed authentications

 Yes No Only * is supported

return_value.response

eq SUCCESS or FAILURE

Filters for the successful or failed response in the returned value

 Yes No Only * is supported

targetUserId.id

eq

 Yes Yes No

targetUserId.immutableId

eq

 Yes Yes No

targetUserId.session.authenticationMethod

eq, co, sw, ew

 Yes No Yes

Search parameters:

Parameter Description Operators supported

tokenized

Defines if the records should be tokenized to protect PII in the audit data

 eq true or false

verify

Defines if the integrity check should be performed on the records

 eq true or false
Copy

Sample Request URI

[POST] /scim/{tenant}/v2/AuditRecords/.search
Copy

Sample request

POST /scim/{tenant}/v2/AuditRecords/.search
{
    "filter": "created gt 2022-11-27T12:00:00Z and verify eq true",
    "count": 10,
    "startIndex": 1,
    "sortBy": "created",
    "sortOrder": "ascending"
}

Where:

  • The filter attribute must be used to reduce the number of records returned:

    Use the and operator between filters and use parentheses between conditions.

    • Successful or failed authentications:

      result eq RESPONSE_SUCCESS
      result eq RESPONSE_FAILURE

    • Records between two dates:

      created gt 2022-11-27T09:00:00Z and created lt 2022-11-28T12:00:00Z

  • You can also use the verify parameter to check the integrity of the records:

    verify eq true

  • The following attributes can be used for a paginated search:

    • count can be used to limit the size of the search results

    • startIndex specifies the index of the first result returned (where 0 will returned the same paginated result as 1)

    The result will contain a totalResults attribute to allow you to compute the number of pages.

    Important:

    The maximum number of rows returned per request is 100, even if you specify a higher count value. Therefore, for lists that are longer than 100 elements, it is mandatory for you to paginate the results.

  • The search results can be sorted using:

    • sortBy - the created filter (the record's timestamp)

    • sortOrder - either ascending or descending (or asc or desc)

Note: For further information, see Searching with the SCIM API.
Copy

Sample response

HTTP/1.1 200 OK
Date: Wed, 04 Jan 2023 16:05:52 GMT
Content-Type: application/scim+json;charset=utf-8
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 162,
    "resources": [
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
            "id": "IDP-test-company",
            "targetUserId": {
                "id": "admin@company.com",
                "immutableId": "11092",
                "session": {
                    "id": "1ea9ac7d7236aa0dce70d63fccb2779411c29478b0ea66cef815bb758479c1cf",
                    "authenticationMethod": "AT_STDPWD"
                }
            },
            "action": {
                "actionName": "indirectPrimaryAuthenticateUP",
                "actionParameters": {
                    "ATC": "AT_STDPWD",
                    "USN": "null",
                    "Action": "indirectPrimaryAuthenticateUP",
                    "ANS": "false",
                    "ARP": "CONTEXT[{\"OPENID\":{\"clientid\":\"r7wcHxsAGjT7jweAjtQCwMw6\",\"scope\":\"openid profile\"}}]",
                    "AUS": "ENABLED",
                    "CHC": "CH_EXTRAPP"
                }
            },
            "result": "RESPONSE_SUCCESS",
            "return_value": {
                "response": "SUCCESS"
            },
            "tenantId": "tdf1808f3d368517208759",
            "actingUserId": {
                "id": "r7wcHxsAGjT7jweAjtQCwMw6",
                "immutableId": "200",
                "session": {
                    "id": "16c52d7ae20de197ca8eecf9bb6ec566e5d8b21e03538632e9fdf3d84b6e1f73"
                }
            },
            "integrityStatus": "validated",
            "created": "2023-01-04T16:04:34.678Z",
            "host": "<host-ip>"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
            "id": "IDP-test-company",
            "targetUserId": {
                "id": "r7wcHxsAGjT7jweAjtQCwMw6",
                "immutableId": "200",
                "session": {
                    "authenticationMethod": "AT_SYSLOG"
                }
            },
            "action": {
                "actionName": "primaryAuthenticateUP",
                "actionParameters": {
                    "ATC": "AT_SYSLOG",
                    "USN": "null",
                    "Action": "primaryAuthenticateUP",
                    "ANS": "false",
                    "ARP": "CONTEXT[{\"OPENID\":{\"clientid\":\"r7wcHxsAGjT7jweAjtQCwMw6\",\"scope\":\"openid profile\"}}],HOSTADDRESS[10.7.252.38]",
                    "AUS": "ENABLED",
                    "CHC": "CH_EXTRAPP"
                }
            },
            "result": "RESPONSE_SUCCESS",
            "return_value": {
                "response": "SUCCESS"
            },
            "tenantId": "tdf1808f3d368517208759",
            "actingUserId": {
                "id": "r7wcHxsAGjT7jweAjtQCwMw6",
                "immutableId": "200",
                "session": {
                    "id": "16c52d7ae20de197ca8eecf9bb6ec566e5d8b21e03538632e9fdf3d84b6e1f73"
                }
            },
            "integrityStatus": "validated",
            "created": "2023-01-04T16:04:23.268Z",
            "host": "<host-ip>"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
            "id": "API-test-company",
            "targetUserId": {
                "id": "afiuser1",
                "immutableId": "11072",
                "session": {
                    "authenticationMethod": "AT_EMPOOB"
                }
            },
            "action": {
                "actionName": "registerUserForOutOfBand",
                "actionParameters": {
                    "ATC": "AT_EMPOOB",
                    "Action": "registerUserForOutOfBand",
                    "DSN": "11297",
                    "DID": "11294",
                    "CHC": "OPERATOR"
                }
            },
            "message": "Registration successful",
            "result": "RESPONSE_SUCCESS",
            "return_value": {
                "response": "SUCCESS"
            },
            "tenantId": "tdf1808f3d368517208759",
            "actingUserId": {
                "id": "SAXLGROUU9npqp4M5A1gO4kE",
                "immutableId": "10033",
                "session": {
                    "id": "9c21b4689c0e59196660c8af60d1c195413ce8fcc68c532fb5c5337b6f5093be"
                }
            },
            "integrityStatus": "validated",
            "created": "2022-12-15T15:18:46.983Z",
            "host": "<host-ip>"
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 100
}

Where:

  • resources is an array of audited records

  • Each record in the response includes the integrityStatus property with one of the following values:

    • validated

    • tainted

    • unverified

Important:

If you detect a tampered record on your tenant, contact the HID Global Technical Support immediately.

Note: The record is detokenized, and the field "jws" is not returned in the response as it cannot be read.