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
Create an OKM
Sending a POST to the /okms endpoint creates an OKM .
Example request:
POST /okms
{
"id":"OKM3",
"serial": "0203cc1fc4123456",
"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
},
"active": true,
"online": true,
"last_sync_time": "2024-05-14T15:29:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483",
"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 using 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. | |
| active | boolean | Unused. | |
| online | boolean | Unused. | |
| 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 | This object contains the URLs that the OKM is subscribed to. | |
| 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. |
The response for success:
HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8
{
"status": 201,
"msg": "Okm registered successfully",
"data": {
"okm": {
"id": "OKM3",
"serial": "0203cc1fc4123456",
"customer": "invue-mastercard",
"active": true,
"online": true,
"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
},
"last_sync_time": "2024-05-14T15:29:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483"
}
}
}
Possible errors
| Error Code | Description |
|---|---|
| 400 Bad Request | OKM already exists. Validation failed for the request. |
| 401 Unauthorized | The accessToken is invalid or has been revoked. |
GET
Get All OKMs for a Customer
Returns the OKMs for the customer in the token. 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": "0203cc1fc4123456",
"customer": "invue-mastercard",
"active": true,
"online": true,
"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
},
"last_sync_time": "2024-05-14T15:29:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483"
},
{
"id": "OKM4",
"serial": "0203cc1fc4123457",
"customer": "invue-mastercard",
"active": true,
"online": true,
"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
},
"last_sync_time": "2024-05-14T15:30:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483"
}
],
"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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"status": 200,
"msg": "OKM fetched successfully",
"data": [
{
"id": "OKM1",
"serial": "0203cc1fc4123456",
"customer": "invu",
"active": true,
"online": true,
"user_data": {},
"config": {
"pin_mode": false,
"cache_mode": true,
"card_reader": {},
"contact_type": 1,
"checkout_window": 30,
"polling_interval": 150
},
"last_sync_time": "2024-05-14T15:30:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483"
}
],
"pagination": {
"page": "1",
"results_per_page": "20",
"total_results": "1"
}
}
Get One OKM by ID
Returns the OKM by ID.
GET /okms/{okm-id}?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",
"active": true,
"online": true,
"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
},
"last_sync_time": "2024-05-14T15:29:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483"
}
}
}
Possible errors
| Error code | Description |
|---|---|
| 401 Unauthorized | The accessToken is invalid or has been revoked. |
| 404 Not Found | OKM with id {{okm-id}} not found |
DELETE
Delete an OKM
Deletes an OKM.
DELETE /okms/{{okm-id}}?customer={customer}
Returns a 204 with an empty body.
Possible errors
| Error code | Description |
|---|---|
| 400 Bad request | OKM with id {{okm-id}} or {{customer-id}} not found |
| 401 Unauthorized | The accessToken is invalid or has been revoked. |
| 404 Not Found | OKM with id {{okm-id}} 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 last_sync_time and fw_version values. It is updated when the OKM connects.
PUT https://api.invue.com/v1/okms/{{okm-id}}?customer={customer}
Example request:
{
"id": "OKM3",
"serial": "0203cc1fc4123456",
"customer": "invu",
"active": false,
"online": true,
"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
},
"last_sync_time": "2024-05-14T15:29:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483"
}
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": "0203cc1fc4123457",
"customer": "invu",
"active": false,
"online": true,
"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
},
"last_sync_time": "2024-05-14T15:29:23.638Z",
"subscribe_urls": {},
"fw_version": "01932023020111483"
}
}
}
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 {{okm-id}} not found |
PATCH
Not supported, the request will return
| Error code | Description |
|---|---|
| 405 Method Not Allowed | Cannot PATCH |