Skip to main content

OKM Audit API

The Audit API is designed to handle audit events, an OKM call it when a user checks-in a key. During this process::

  1. Audit events stored in the key are transferred to the OKM.
  2. The OKM sends a POST request to the /embeddedv1/audit/kas endpoint with the event data.

Additionally, for LoRa-enabled keys, there is a dedicated endpoint used by the Live Display server to transmit audit events specific to LoRa-enabled keys: /embeddedv1/audit/key

Redirection​

The /embeddedv1/audit/kas endpoint is the default endpoint for audit records, hard-coded into OKMs. However, this endpoint is not compatible with the API structure of the new tech stack.

To address this, when an OKM makes its initial call to the /config or /audit endpoint, the OKM Service responds by providing a this URL: /api/v1/audit

Once the OKM receives this update, it follows these steps:

  1. Pause Audit Record Transmission: Temporarily stops sending audit records.
  2. Update Endpoint: Updates itself with the new URL;
  3. Resume Audit Record Transmission: Resumes sending audit records to the newly configured endpoint.

This is the endpoint used for the rest of this documentation.

Requests​

Add audit records from an OKM.​

This endpoint is responsible for processing audit records received from an OKM. It performs the following actions:

  1. Forward Records: Forwards the audit records to the URL specified in the environment variable AUDIT_DEST_URL.
  2. Update Sync Time: Updates the last_sync_time value for the corresponding OKM in the database.

Verb and URL:​

POST embeddedv1/audit/kas/{serialNumber}

Params and query params:​

  1. serialNumber: string, a valid OKM serial number.

Body:​

  1. Description: a byte array of audit events.
  2. Type: binary

Details:​

  1. Bytes [0, 28[ : header
  2. Bytes [16, 19]: 4 bytes for event count as a 32-bit big endian unsigned int
  3. Bytes [24, 27]: 4 bytes for IP address as <27>.<26>.<25>.<24>

If the OKM is not found, a 404 is returned.

Responses:​

  1. If the audit_enabled configuration parameter of the OKM is false, the audit records a dropped and a 200 is returned.
  2. If there are no audit records in the body of the request, a 200 is returned.
  3. If there are no URLs in subscribe_urls.audit, the audit records a dropped and a 200 is returned.
  4. For one forward to a subscribe_urls.audit URLs fails, a 424 is returned with the error in the message.
  5. If the audit records are successfully forwarded to all URLs in subscribe_urls.audit, a 200 is returned.
  6. Any other exception will result in a 500 returned with the error in the message.