Skip to main content

OKM Config API

At a regular interval (see pollingInterval below), OKMs send a request to the /config endpoint of the OKM Service.

The OKM Service will then:

  1. check if it knows this OKM;
  2. if so, update the last sync time, last IP, and firmware version of the OKM stored in the database;
  3. go through the URLs in the okm subscribe_urls.status array and send last sync time, last IP, and firmware version;
  4. then compare the value of each parameter in the request to what is configured for this OKM;
  5. If the OKM device isn't found in the system, it gets added to the database. After inserting, it sends a 204 No Content response.
  6. The resolver compares the data received from the OKM with the data stored in the system.
    • If there is a difference, the resolver informs the OKM by sending the updated data, allowing the OKM to update itself.
    • If the data matches, no action is taken, and the process moves to the next resolver.
    • Resolvers operate sequentially, handling one comparison at a time before proceeding to next resolver

Verb and URL​

The URL for the config endpoint that the OKM calls is configurable, though it is hard-coded in the OKM as embeddedv1/kas/config. Because of this, it is the first URL the OKM will call. At this endpoint, the OKM Service will check what is the configured endpoint for config and return that to the OKM. From then on, the OKM will call this configured endpoint.

By default, the configured endpoint is /api/v1/config .

GET /config/{serialNumber}?kasFirmware={okmFirmwareVersion}&kasDateTime={okmDateTime}&retailCfg={retailConfigType}&configUrl={configURL}&auditUrl={auditURL}&assetList={assetListDigest}&usersAssets={userAssetsDigest}&batchKeyFirmware={batchKeyFirmwareVersion}&wirelessKeyFirmware={loRaKeyFirmwareVersion}&keyCheckoutWindowTime={keyCheckoutWindowTime}&keyCheckoutWindowContact={keyCheckoutWindowContact}&installCode={installerCode}&cacheMode={cacheMode}&pollingInterval={pollingInterval}

Parameters and Query Parameters​

Param / Query ParamTypeDescriptionAction
serialNumberInVue Serial NumberSerial number of the OKM making the call. This is used to retrieve the OKM’s info from the database.None
kasFirmwareVersion NumberVersion of the f/w of the calling OKM. If the latest version of the f/w known is more recent than this value, return a URL to fetch the most recent firmware.Check if the latest firmware is more recent that this value, if it is, a URL is returned to the OKM where it can fetch the latest f/w version.
kasDateTimeTimestampOKM time as a timestamp in millis to synch with the service.If time in OKM is 5 minutes behind last_sync_time, the service replies with the current time.
retailCfgNumberRetail Config Type supported by the OKM. 2 = retailCfg_IR3ZonePlusAudit_eN/A
configURLURLThe URL that the OKM calls for this endpoint.Currently always returns api/v1/config if the configURL value is different.
auditURLURLThe URL that the OKM calls to send audit messages.Currently always returns api/v1/audit if the auditURL value is different.
assetListSHA256 HashHash of the asset list of this OKM. If it doesn’t match what the service has, the service replies with its asset list.Compare the value received with the value in the database, and if different, return the value in the database.
usersAssetsSHA256 HashHash of the user asset list of this OKM. If it doesn’t match what the service has, the service replies with its user asset list.Compare the value received with the value in the database, and if different, return the value in the database.
batchKeyFirmwareVersion NumberVersion number of the batch key f/w this OKM contains. If the latest version of the f/w known is more recent than this value, returns a URL to fetch the most recent firmware.Check if the latest firmware is more recent that this value, if it is, a URL is returned to the OKM where it can fetch the latest f/w version.
wirelessKeyFirmwareVersion NumberVersion number of the LoRA key f/w this OKM contains. If the latest version of the f/w known is more recent than this value, returns a URL to fetch the most recent firmware.Check if the latest firmware is more recent that this value, if it is, a URL is returned to the OKM where it can fetch the latest f/w version.
keyCheckoutWindowTimeNumberNumber of seconds someone has to check out a key.If it’s different than what’s been configured for this OKM, the new value is returned.
keyCheckoutWindowContactStringType of contact: ”open” = normally open ”closed” = normally closedIf it’s different than what’s been configured for this OKM, the new value is returned.
installerCodeNumberInstaller code of the OKM. Number between 5 and 20 digits.Not used by the service yet.
cacheModeNumberTell LA the currently configured cacheMode of this OKM. 0 : unknown 1 : disabled 2 : enabledIf it’s different than what’s been configured for this OKM, the new value is returned.
pollingIntervalNumberNumber of seconds between OKM /config calls or idle communications with the OKM Service. Minimum value is 5, and maximum value is 3600. The default is 150.If it’s different than what’s been configured for this OKM, the new value is returned.

Details of the /config Endpoint Parsing​

When the service receives a config requests from an OKM, it parses the request using a stack of “resolvers”. Each resolver is responsible for evaluating 1 parameter.

The resolvers do not directly change or update anything on the OKM. Their only job is to compare the data sent by the OKM with the data stored in the system.

  1. If the data matches, the resolver does nothing and moves on to the next resolver.
  2. If the data doesn't match, the resolver replies to the OKM with the updated data so the OKM can update itself.

The current stack is as follows:

1. OKM Existence Check​

  • Purpose: Verifies if the OKM exists in the database.
  • Operation:
    1. If the OKM device isn't found in the system, it gets added to the database. After inserting, it sends a 204 No Content response.
    2. Updates the last_sync_time and firmware version in the database.

2. Buffered Message Check​

  • Purpose: Handles and sends buffered (saved) messages to the OKM if they differ from what is stored in the database.
  • Operation:
    1. Checks if there’s a buffered (saved) message in DB (delete assets message for example).
    2. If messages exist, send message to the OKM.

3. Firmware Resolver​

  • Purpose: The firmware resolver is the first step in the resolution process. It ensures the OKM operates on the latest firmware version.
  • Operation:
    1. Checks if the OKM has the most recent firmware version available.
    2. If there is, returns the URL to the firmware file.

4. Date-Time Resolver​

  • Purpose: Synchronizes the OKM's date and time with the service by updating it if there is a difference of more than 5 minutes.
  • Operation:
    1. Check if the OKM date and time is synchronized with the service
    2. If there’s more than a 5 minute difference, returns the current server time.

5. Cache Mode Resolver​

  • Purpose: Aligns the OKM's cache mode with the configured setting by updating it if there is a difference.
  • Operation:
    1. Compares the OKM cache mode with the one configured.
    2. If different or unknown, send the currently configured value back to the OKM.
    3. If cacheMode is not supported, then disabled is returned to the OKM.

6. Key Checkout Window Resolver​

  • Purpose: Synchronizes the OKM's configuration for checkout window time and contact type by updating them if they differ.
  • Operation:
    1. Compares OKM configuration with the settings stored in the database for both check-out window time and contact type.
    2. If different, send settings to OKM.

7. Retail Config Resolver​

  • Purpose: Compares the OKM retail configuration with the service and updates the configuration if there is a difference.
  • Operation:
    1. Compares the OKM retail configuration with the service.
    2. If auditing is enabled, returns retailCfg_IR3ZonePlusAudit_e to the OKM.

8. Asset List Resolver​

  • Purpose: Compares the OKM's asset list with the service's version.
  • Operation:
    1. Compares the received asset list digest with the service version.
    2. If mismatched, return the new asset list to the OKM.

9. User Assets Resolver​

  • Purpose: Verifies the OKM's user-specific asset list against the service's version.
  • Operation:
    1. Compares the user asset list digest received with the one from the service.
    2. If different, return the new user asset list to the OKM.

10. Audit URL Resolver​

  • Purpose: Checks the auditUrl and updates it if it is missing or incorrect.
  • Operation:
    1. If auditUrl is missing or incorrect or it is not /api/v1/audit , return /api/v1/audit.
    2. While this resolver doesn’t seem to do anything useful because the return value is pre-defined for now, it allows us to return a different audit URL if needed.

11. Polling Interval Resolver​

  • Purpose: Checks if the OKM's polling interval matches the service's setting.
  • Operation:
    1. Compares the OKM's polling interval with the one configured.
    2. If different or unknown, send currently configured value back to the OKM.

12. Batch Key Firmware Resolver​

  • Purpose: Checks for differences in batch key firmware versions.
  • Operation:
    1. Checks if there is a more recent batch key firmware version.
    2. If available, returns the firmware file URL.

13. Wireless Key Firmware Resolver​

  • Purpose: Validates the wireless key firmware version on the OKM.
  • Operation:
    1. Checks if the most recent wireless key firmware version available.
    2. If available, returns the firmware file URL.

References​

F1721 IR4 Ecosystem - Audit Trail and Event Record Format

F1721 IR4 Ecosystem - KAS Ethernet Interface Design