OKM CRUD API

The OKM resource is used to create and maintain OKMs. Each OKM is required to be registered into the service to receive ACL digests.

POST

Several things can be done with a POST request:

1. Create an OKM.
2. Clear the assets of an OKM: prepares a message for the OKM to send on its next successful config request.
3. Refresh the API access token of an OKM: creates a new API access token and marks it as unclaimed.
4. Clear the API access token of an OKM: deletes the API access token.

Create an OKM

Sending a POST to the /okms endpoint creates an OKM .

Example request:

POST /okms

{ 
  "id": "OKM3",
  "serial": "0203CC1FFFFFFFFF",
  "customer": "invu",
  "config": {
    "contact_type": 1,
    "checkout_window": 0,
    "cache_mode": true,
    "pin_mode": false,
    "card_reader": {},
    "audit_enabled": true,
    "retail_config": 2,
    "polling_interval": 150,
    "date_time_threshold": 60
  },
  "last_ip": "::ffff:1.2.3.0/120",
  "last_sync_time": "2024-05-14T15:29:23.638Z",
  "fw_version": "01932023020111483",
  "subscribe_urls": {
    "audit": ["https://localhost:8080/api/v1/audit/okms/0203CC1FFFFFFFFF"],
    "status": ["https://localhost:8080/api/v1/audit/okms/0203CC1FFFFFFFFF/status"]
  },
  "user_data": {},
}

Where the payload is:

Field		Type	Description
id		string	This is the OKM id. It is used as the identifier when referenced in other API calls. This ID must be unique. Implementor can make this the same as the serial number if required.
serial		string	This is the OKM’s serial number.
customer		string	The customer that owns this OKM.
config		object	This object contains the OKM configuration information.
	contact_type	number	0 or 1 Used in 2-step authentication. This flag when = 0 causes the OKM to wait for contact closure before key checkout. This is used with external biometric devices or any other switch capable device.
	checkout_window	number	[0, 254] Used in 2-step authentication. This is the amount of time in seconds a user has to checkout a key, following the activation of a secondary device. Set it to 0 to deactivate 2-step authentication (this is the usual case).
	cache_mode	boolean	true or false This flag causes the OKM to operate in Cached Mode when true. When false, the OKM will operate in non-cached mode and fetch the ACL for the user each time a key is checked out.
	pin_mode	boolean	true or false When true the OKM to operate in PIN only mode. This mode is similar to the retail version where only a pin is required to check out a key. When false, the OKM will require a User Id and a Pin to checkout a key.
	card_reader	JSON	This object contains the card reader configuration. The content of this object is to be defined.
	audit_enabled	boolean	true or false This is a forgotten setting that is used in some enable or disable audit records. The OKM will send a value for this, so the service needs to be able to reply with something. Even if it’s always “true” we should leave it to indicate it’s a setting that’s available.
	retail_config	number	2 This is an old setting that is kept for compatibility reason. Leave it to 2.
	polling_interval	number	[5, 3600] This is the amount of time in seconds between OKM “heartbeats” or idle communications with the OKM Service. The default is 150.
	date_time_threshold	number	Number of seconds to allow between the OKM’s clock and the current time.
last_ip		string	IP address the OKM used when it last connected to send a request to /config or /audit . Value will have this format: ::ffff:1.2.3.0/120
last_sync_time		ISO date/time	Last date and time this OKM connected. While it is possible to pass a value when creating an OKM, nothing should be passed on create. The update of this value should only be left to the config and audit endpoints, when an OKM connects to the service.
subscribe_urls		JSON	JSON with URLs to call for certain events. Currently supports: audit, an array of URLs to call to send audit events; status, an array of URLs to call to send status updates, which at this time sends last sync time, last IP, and firmware version.
fw_version		string	Version number of the OKM firmware.
user_data		object	This is a field where the implementer can store app related information. The OKM Service does not use this data. This data is returned when the OKM is fetched from the API.
desired_firmware_type		string	Optional, with two possible values: OKM_ENCRYPTED or OKM. Defaults to OKM if not provided.

Note: last_sync_time, last_ip, and fw_version should not be set through a POST request. The values will be updated when an OKM connects, and setting them manually could introduce unspecified behaviour. They are taken into account in POST requests anyway, in case they are needed to set up tests, clone environments, etc.

The response for success will include all fields sent with the POST:

HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8

{
  "status": 201,
  "msg": "Okm registered successfully",
  "data": {
    "okm": {
      "id": "OKM3",
      "serial": "0203CC1FFFFFFFFF",
      "customer": "invu",
      "user_data": {},
      "config": {
        "contact_type": 1,
        "checkout_window": 0,
        "cache_mode": true,
        "pin_mode": false,
        "card_reader": {},
        "audit_enabled": true,
        "retail_config": 2,
        "polling_interval": 150,
        "date_time_threshold": 60
      },
      "last_sync_time": "2024-05-14T15:29:23.638Z",
      "last_ip": "::ffff:1.2.3.0/120",
      "subscribe_urls": {
        "audit": ["https://localhost:8080/api/v1/audit/okms/0203CC1FFFFFFFFF"],
        "status": ["https://localhost:8080/api/v1/audit/okms/0203CC1FFFFFFFFF/status"]
      },
      "fw_version": "01932023020111483",
      "desired_firmware_type": "OKM"
    }
  }
}

If the OKM already exists:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "status": 400,
  "error_code": "ALREADY_EXISTS",
  "error_msg": "OKM already exists"
}

Possible errors

Error Code	Description
400 Bad Request	Validation failed for the request.
401 Unauthorized	The accessToken is invalid or has been revoked.

Clear the Assets of an OKM

This tells the service to prepare a reset assets message for the OKM, which will be sent to the OKM on its next successful /config request.

In more words, the service will create a msgTkn_deleteAssetsAndUsers_e message and store it for that OKM. The next time a /config request is received for that OKM, the service will reply with that command. The OKM will then clear its assets before calling back /config again.

POST /okms/:okmId/clear?customer=:customer

Returns a 200 with an empty body.

Possible errors

Error code	Description
400 Bad Request	The okmId or the customer is missing.
401 Unauthorized	The accessToken is invalid or has been revoked.
404 Not Found	OKM with id okmId not found.

GET

Get All OKMs for a Customer

Returns the OKMs for the customer in the request. The number of records returned depends on the default results per page, if pagination options are not passed as query parameters.

GET /okms?customer=:customer

Example response:

When OKMs are present in the system:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": 200,
  "msg": "OKM fetched successfully",
  "data": [
    {
      "id": "OKM3",
      "serial": "0203CC1FFFFFFFFF",
      "customer": "invu",
      "user_data": {},
      "config": {
        "contact_type": 1,
        "checkout_window": 0,
        "cache_mode": true,
        "pin_mode": false,
        "card_reader": {},
        "audit_enabled": true,
        "retail_config": 2,
        "polling_interval": 150,
        "date_time_threshold": 120
      },
      "last_sync_time": "2024-05-14T15:29:23.638Z",
      "last_ip": "::ffff:1.2.3.0/120",
      "subscribe_urls": {
        "audit": ["https://localhost:8080/api/v1/audit/okms/0203CC1FFFFFFFFF"],
        "status": ["https://localhost:8080/api/v1/audit/okms/0203CC1FFFFFFFFF/status"]
      },
      "fw_version": "01932023020111483"
    },
    {
      "id": "OKM4",
      "serial": "0203cc1fc4123457",
      "customer": "invu",
      "user_data": {},
      "config": {
        "contact_type": 1,
        "checkout_window": 0,
        "cache_mode": true,
        "pin_mode": false,
        "card_reader": {},
        "audit_enabled": true,
        "retail_config": 2,
        "polling_interval": 150,
        "date_time_threshold": 180
      },
      "last_sync_time": "2024-05-14T15:30:23.638Z",
      "last_ip": "::ffff:1.2.3.0/120",
      "subscribe_urls": {
        "audit": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123457"],
        "status": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123457/status"]
      },
      "fw_version": "01932023020111483",
      "desired_firmware_type": "OKM"
    }
  ],
  "pagination": {
    "page": 1,
    "results_per_page": 30,
    "total_results": "2"
  }
}

When there are no OKMs:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": 200,
  "msg": "OKM fetched successfully",
  "data": [],
  "pagination": {
    "page": 1,
    "results_per_page": 30,
    "total_results": "0"
  }
}

Get All OKMs for the customer with pagination params

Returns the OKMs, sorted by ID.

GET /okms?customer=invu&page=1&results_per_page=20

Example response is the same as for a normal GET, as shown above.

Possible errors

Error code	Description
401 Unauthorized	The accessToken is invalid or has been revoked.

Get One OKM by ID

Returns the OKM by ID.

GET /okms/:okmId?customer=:customer

When the OKM is found:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": 200,
  "msg": "Lock fetched successfully",
  "data": {
    "okm": {
      "id": "OKM3",
      "serial": "0203cc1fc4123456",
      "customer": "invu",
      "user_data": {},
      "config": {
        "contact_type": 1,
        "checkout_window": 0,
        "cache_mode": true,
        "pin_mode": false,
        "card_reader": {},
        "audit_enabled": true,
        "retail_config": 2,
        "polling_interval": 150,
        "date_time_threshold": 60
      },
      "last_sync_time": "2024-05-14T15:29:23.638Z",
      "last_ip": "::ffff:1.2.3.0/120",
      "subscribe_urls": {
        "audit": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123456"],
        "status": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123456/status"]
      },
      "fw_version": "01932023020111483",
      "desired_firmware_type": "OKM"
    }
  }
}

Possible errors

Error code	Description
401 Unauthorized	The accessToken is invalid or has been revoked.
404 Not Found	OKM with id okmId not found

DELETE

Delete an OKM

Deletes an OKM.

DELETE /okms/:okmId?customer=:customer

Returns a 204 with an empty body.

Possible errors

Error code	Description
401 Unauthorized	The accessToken is invalid or has been revoked.
404 Not Found	OKM with id okmId not found.

PUT

Update an Existing OKM

Sending a PUT to the /okms endpoint will update a OKM .

It’s not possible to update the customer and the serial number, because it must not be possible for a customer to assign a new customer to an OKM of another customer.

It’s not possible to update last_sync_time, last_ip, and fw_version, because these values should only be updated when an OKM connects.

It’s not possible to update the optional desired_firmware_type field from "OKM_ENCRYPTED" to "OKM". It is a one way conversion.

PUT https://api.invue.com/v1/okms/:okmId?customer=:customer

Example request:

{
  "id": "OKM3",
  "serial": "0203cc1fc4123456",
  "customer": "invu",
  "user_data": {},
  "config": {
    "contact_type": 1,
    "checkout_window": 0,
    "cache_mode": false,
    "pin_mode": false,
    "card_reader": {},
    "audit_enabled": true,
    "retail_config": 2,
    "polling_interval": 350,
    "date_time_threshold": 60
  },
  "subscribe_urls": {
    "audit": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123456"],
    "status": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123456/status"]
  }
}

Where the payload is the same as when creating an OKM.

The response for success:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "status": 200,
  "msg": "Okm updated successfully",
  "data": {
    "okm": {
      "id": "OKM3",
      "serial": "0203cc1fc4123456",
      "customer": "invu",
      "user_data": {},
      "config": {
        "contact_type": 1,
        "checkout_window": 0,
        "cache_mode": false,
        "pin_mode": false,
        "card_reader": {},
        "audit_enabled": true,
        "retail_config": 2,
        "polling_interval": 350,
        "date_time_threshold": 60
      },
      "last_sync_time": "2024-05-14T15:29:23.638Z",
      "last_ip": "::ffff:1.2.3.0/120",
      "fw_version": "01932023020111483",
      "subscribe_urls": {
        "audit": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123456"],
        "status": ["https://localhost:8080/api/v1/audit/okms/0203cc1fc4123456/status"]
      }
    }
  }
}

If the OKM does not exist:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "status": 404,
  "error_code": "NOT_EXISTS",
  "error_msg": "OKM not exists"
}

Possible errors

Error code	Description
400 Bad request	OKM id mismatch
401 Unauthorized	The accessToken is invalid or has been revoked.
404 Not Found	OKM with id okmId does not exist.
409 Conflict	Cannot change desired_firmware_type from OKM_ENCRYPTED to OKM.

Refresh the API Access Token of an OKM

Creates a new API access token for the OKM and marks it as unclaimed. This is useful when doing a factory reset of an OKM without deleting it from the system, and then connecting it again to the same system.

POST /okms/:okmId/token/refresh?customer=:customer

Returns a 200 with an empty body.

Possible errors

Error code	Description
400 Bad Request	The okmId or the customer is missing. desired_firmware_type must be one of: OKM, OKM_ENCRYPTED.
401 Unauthorized	The accessToken is invalid or has been revoked.
404 Not Found	OKM with id okmId not found.

Clear the API Access Token of an OKM

Deletes the API access token for the OKM and marks it as unclaimed. This is also useful when doing a factory reset of an OKM without deleting it from the system, and then connecting it again to the same system.

POST /okms/:okmId/token/clear?customer=:customer

Returns a 200 with an empty body.

Possible errors

Error code	Description
400 Bad Request	The okmId or the customer is missing.
401 Unauthorized	The accessToken is invalid or has been revoked.
404 Not Found	OKM with id okmId not found.

PATCH

Not supported, the request will return

Error code	Description
405 Method Not Allowed	Cannot PATCH