View Audit Logs

Identity Cloud stores audit logs for 30 days. Use the /monitoring/logs endpoint to view the stored data.

You need to get an API key and secret before you can authenticate to the endpoints.

Obtaining API credentials

  1. In the Admin UI, click the user icon, and then click Tenant Settings.

    Show me

    tenant menu

  2. On the Global Settings tab, click Log API Keys.

  3. Click New Log API Key, provide a name for the key, and then click Create Key.

    A dialog box appears containing the new keys:

    log api key
  4. Store the api_key_id and api_key_secret values securely.

    You cannot view the api_key_secret value again once you click Done.
  5. Click Done.

Getting sources

Identity Cloud stores audit logs in various sources, to make browsing them simpler.

To get a list of the available sources, use the /monitoring/logs/sources endpoint.

Example request:

curl \
--header 'x-api-key: <API-KEY>' \
--header 'x-api-secret: <API-SECRET>' \
'https://<tenant-name>.forgeblocks.com/monitoring/logs/sources'

Example response:

{
    "result": [
        "<string>",
        "<string>"
    ],
    "resultCount": "<integer>",
    "pagedResultsCookie": "<string>",
    "totalPagedResultsPolicy": "<string>",
    "totalPagedResults": "<integer>",
    "remainingPagedResults": "<integer>"
}

Identity Cloud returns the available sources in the result array.

Viewing logs

To view the stored logs for a source, use the /monitoring/logs endpoint, specifying the source as a parameter.

Example request:

curl  --get \
--header 'x-api-key: <API-KEY>' \
--header 'x-api-secret: <API-SECRET>' \
--data 'source=am-activity' \
'https://<tenant-name>.forgeblocks.com/monitoring/logs'

Example response:

{
    "result": [
        {
            "payload": "<object>",
            "timestamp": "<dateTime>",
            "type": "<string>"
        },
        {
            "payload": "<object>",
            "timestamp": "<dateTime>",
            "type": "<string>"
        }
    ],
    "resultCount": "<integer>",
    "pagedResultsCookie": "<string>",
    "totalPagedResultsPolicy": "<string>",
    "totalPagedResults": "<integer>",
    "remainingPagedResults": "<integer>"
}

Identity Cloud returns the available logs in the result array.

Results are in JSON format, or plaintext, depending on the source you request.

Use the beginTime and endTime query parameters to return records created between the two times.

Specify UTC times, in ISO 8601 format.

For example:

curl --get \
--header 'x-api-key: <API-KEY>' \
--header 'x-api-secret: <API-SECRET>' \
--data 'source=am-activity' \
--data 'beginTime=2020-09-11T09:00:31Z' \
--data 'endTime=2020-09-18T17:30:59Z' \
'https://<tenant-name>.forgeblocks.com/monitoring/logs'

Tailing logs

To tail, or view the latest entries in the stored logs for a source, use the /monitoring/logs/tail endpoint, specifying the source as a parameter.

The first call to the tail endpoint returns results from the last 15 seconds. Subsequent calls (when using _pagedResultsToken for example) return logs from:

  • Time of last line from previous call to tail

  • Log timestamp

  • Now

You can request results in JSON format or plaintext. One source can have both JSON and plaintext logs (for example, when you request am-everything).

Example request:

curl --get \
--header 'x-api-key: <API-KEY>' \
--header 'x-api-secret: <API-SECRET>' \
--data 'source=am-activity' \
'https://<tenant-name>.forgeblocks.com/monitoring/logs/tail'

Example response:

{
    "result": [
        {
            "payload": "<object>",
            "timestamp": "<dateTime>",
            "type": "<string>"
        },
        {
            "payload": "<object>",
            "timestamp": "<dateTime>",
            "type": "<string>"
        }
    ],
    "resultCount": "<integer>",
    "pagedResultsCookie": "<string>",
    "totalPagedResultsPolicy": "<string>",
    "totalPagedResults": "<integer>",
    "remainingPagedResults": "<integer>"
}

You can specify multiple sources in a single call. Example request:

curl --get \
--header 'x-api-key: <API-KEY>' \
--header 'x-api-secret: <API-SECRET>' \
--data 'source=am-access,idm-access,idm-sync,idm-activity' \
'https://<tenant-name>.forgeblocks.com/monitoring/logs/tail'

To keep tailing, take the pagedResultsCookie field and pass it back to the tail endpoint. This retrieves all records stored since that request.

Example request:

curl --get \
--header 'x-api-key: <API-KEY>' \
--header 'x-api-secret: <API-SECRET>' \
--data 'source=am-access,idm-access,idm-sync, \
idm-activity&_pagedResultsCookie=<pagedResultsCookie>'
'https://<tenant-name>.forgeblocks.com/monitoring/logs/tail'

Rate limiting

To reduce unwanted stresses on the system, Identity Cloud limits the number of requests you can make to the /monitoring/logs endpoint in a certain timeframe.

The following rate limit notification headers are sent in the response to each request to the /monitoring/logs endpoint:

X-Rate-Limit-Limit

The maximum number of requests allowed in the current rate limit window.

X-Rate-Limit-Remaining

The number of requests remaining in the current rate limit window.

X-Rate-Limit-Reset

The time at which the rate limit window is reset, specified in UTC epoch time.

More information

For deep dives, see: