Device REST API

The Device endpoint allows creating, importing and managing hardware or software-based devices.

You can also perform specific actions such as device synchronization and PIN unlock.

Devices enable a user to perform authentication to access a protected resource.

Each device is linked to a device type to categorize the device. Device types define device parameters leveraged during user authentication.

Note: The API version supported by HID Authentication Service is 10.3.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/scim/{tenant}/v2/Device/	Get all devices filtered by attributes
GET	Read	/scim/{tenant}/v2/Device/{id}:(String)	Retrieve a known device
POST	Create	/scim/{tenant}/v2/Device/	Create new device Create Import (Synchronous/Asynchronous)
POST	Action	/scim/{tenant}/v2/Device/{id}:(String)	Perform an action on a device Resynchronize OATH Device with OTP Manual Counter Resynchronization PIN Unlock
POST	Search	/scim/{tenant}/v2/Device/.search	Search for device
POST	Create	/scim/{tenant}/v2/Device/.import	Import a new device
PUT	Replace	/scim/{tenant}/v2/Device/{id}.(String)	Assign a device to a known user
DELETE	Delete	/scim/{tenant}/v2/Device/{id}.(String)	Delete a known device

Required Permissions

Function	Required Permissions
GET	Read device details Search users
CREATE	Add device Search users
REPLACE	Read device details Read user details Unassign device Assign device Read reference data Update device Search users
DELETE	Delete device

Create a Device

[POST] /Device

Accept: application/scim+json

Status can be:

ACTIVE
PENDING

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Device

Copy

Sample Request

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
    "externalId": "myExternalId",
    "type": "DT_TDSV4",
    "status": {
        "status": "PENDING",
        "expiryDate": "2019-06-12T14:46:58+02:00",
        "startDate": "2017-06-12T14:46:58+02:00"
    }
}

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
   "id": "11326",
   "externalId": "myExternalId",
   "meta":    {
      "resourceType": "Device",
      "created": "2017-11-20T16:21:15Z",
      "location": "https://[base-server-url]/scim/tenant/v2/Device/11326",
      "version": "1"
   },
   "friendlyName": "",
   "type": "DT_TDSV4",
   "status":    {
      "status": "PENDING",
      "active": false,
      "expiryDate": "2019-06-12T12:46:58Z",
      "startDate": "2017-06-12T12:46:58Z"
   }
}

Get a Device

[GET] /Device/{id}

Copy

Sample Request URI where the Device is attached to a user (owner section) and has two credentials (children section)

[GET] /scim/{tenant}/v2/Device/1289

Copy

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json+scim, 
Location: https://[base-server-url]/SCIM/tenant/v2/Device/1289
 
{
   "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
   "id": "11289",
   "externalId": "11289",
   "meta":    {
      "resourceType": "Device",
      "location": "https://[base-server-url]/scim/tenant/v2/Device/11289",
      "version": "1"
   },
   "type": "DT_OOB",
   "status":    {
      "status": "ACTIVE",
      "active": true
   },
   "owner":    {
      "type": "User",
      "display": "jdoe",
      "value": "11288",
      "$ref": "https://[base-server-url]/scim/tenant/v2/Users/11288"
   },
   "children":    [
            {
         "value": "11290",
         "$ref": "https://[base-server-url]/scim/tenant/v2/Credential/11290"
      },
            {
         "value": "11291",
         "$ref": "https://[base-server-url]/scim/tenant/v2/Credential/11291"
      }
   ]
}

Import Devices

Note: This release of the API only supports importing PSKC, SDS and PKI files.

[POST] /Device/.import

The parameters are:

Parameter	Description
`adapter`	Code of the adapter to use (OATH-PSKC, SDS and PKI are supported in this release) mapping – array of objects representing a mapping (deviceType and algo)
`binding`	Object representing the binding between the deviceType and the associated credentialType to import
`encryptionKey`	Encryption key (in hexadecimal string format)
`resyncWindow`	Resynchronization window
`status`	Status of the device after import (ACTIVE or PENDING)
`owner`	(Optional) Reference of the user to who the device should be assigned If owner is specified, either value or display must also be specified: value - userId (for example, 12345) display - userCode (for example, user01)
`policy`	(Optional) Reference of the authentication policy for creating the user authenticator If policy is specified, the owner must also be specified: value - authentication policy code (for example, AT_EMPPKI)
`payload`	Binary of the file to import, encoded in base64
`async`	Indicates if the import is synchronous or asynchronous
`correlationId`	(Optional) If no correlationId is specified, a random one is generated. The correlationId will appear in all audit records for this import.
`startDate`	(Optional) Can be used to define a "valid from" date for devices and credentials
`endDate`	(Optional) Can be used to define a "valid to" date for devices and credentials

Note: The date format for startDate and endDate is dd/MM/yyyy.

Import Mapping Parameter

This mapping defines the deviceType to use during device creation depending on the algorithm(s) found in the file.

Possible values for algo are:

ai – short name for HID tokens
hotp – short name for OATH HMAC-based OTP
totp – short name for OATH Time-based OTP
ocra – short name for OATH Challenge Response algorithm

Note: The value for algo is not case-sensitive.

Only the slots from the file with ai, hotp, totp or ocra algorithms with be imported. Other entries using a different algo will be ignored.

If a slot uses ai, hotp, totp or ocra, the mapping must define a deviceType for the corresponding algo.

If there are multiple slot entries with the OCRA algorithm for the same device, then the slot’s OCRA suite must be used to map the correct deviceType (see the following examples).

Copy

Example of a mapping for a .pskc file containing only the TOTP algo

"mapping": [{
    "deviceType": "DT_MIN_OT",
    "algo": "TOTP"
}]

Copy

Example of a mapping for a .pskc file containing the HOTP and OCRA algos

"mapping": [{
    "deviceType": "DT_FXT_OE",
    "algo": "HOTP"
}, {
    "deviceType": "DT_FXT_OA",
    "algo": "OCRA"
}]

Copy

Example of a mapping for a .pskc containing the HOTP algo and two different OCRA entries with different OCRA suites

"mapping": [{
    "deviceType": "DT_FXT_OE",
    "algo": "HOTP"
}, {
    "deviceType": "DT_FXT_OA_1",
    "algo": "OCRA-1:HOTP-SHA1-8:QA08-T30S"
}, {
    "deviceType": "DT_FXT_OA_2",
    "algo": "OCRA-1:HOTP-SHA1-8:QA32-T30S"
}]

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Device/.import

Copy

Sample Request for PSKC

{
    "adapter" : "OATH-PSKC",
    "mapping": [{
            "deviceType": "DT_FXT_OE",
            "algo": "HOTP"
        }, {
            "deviceType": "DT_FXT_OT",
            "algo": "TOTP"
        }, {
            "deviceType": "DT_FXT_OA",
            "algo": "OCRA"
        }
    ],
    "encryptionKey" : "11111111222222223333333344444444",
    "resyncWindow" : "20",
    "status" : "ACTIVE",
    "payload": "<binary file content - base64 encoded>",
    "async": false
}

Copy

Sample Request for PKI

POST /scim/{tenant}/v2/Device/.import
{
    "adapter": "PKI",
    "binding": {
        "deviceType": "DT_SCPKI",
        "credentialType" : "CT_CRTCHK1"
    },
    "status": "ACTIVE",
    "owner": {
        "value": "13060"
    },
    "policy": {
        "value": "AT_EMPPKI"
    },
    "payload": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURqekNDQW5lZ0F3SUJBZ0l...<truncated>"
}

Sample Response for PSKC

Depending on the async parameter, there are two types of PSKC responses:

Copy

Sample response if async is set to false, it is a synchronous call and the API waits for the response

{
    "results": [{
            "device": {
                "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
                "id": "370908",
                "externalId": "14714876330461",
                "meta": {
                    "resourceType": "Device",
                    "location": "https://[base-server-url]/scim/tenant/v2/Device/370908",
                    "version": "1"
                },
                "type": "DT_FXT_OE",
                "status": {
                    "status": "ACTIVE",
                    "active": true
                }
            },
            "result": 101,
            "reason": "Imported Token"
        }, {
            "device": {
                "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
                "id": "370910",
                "externalId": "147148763304612",
                "meta": {
                    "resourceType": "Device",
                    "location": "https://[base-server-url]/scim/tenant/v2/Device/370910",
                    "version": "1"
                },
                "type": "DT_FXT_OT",
                "status": {
                    "status": "ACTIVE",
                    "active": true
                }
            },
            "result": 101,
            "reason": "Imported Token"
        }, {
            "device": {
                "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
                "id": "370912",
                "externalId": "147148763304613",
                "meta": {
                    "resourceType": "Device",
                    "location": "https://[base-server-url]/scim/tenant/v2/Device/370912",
                    "version": "1"
                },
                "type": "DT_FXT_OA",
                "status": {
                    "status": "ACTIVE",
                    "active": true
                }
            },
            "result": 101,
            "reason": "Imported Token"
        }
    ]
}

Copy

Sample response if async is set to true, it is an asynchronous call and the API does not wait for the response.

{
    "results": [],
    "correlationId": "1SFCBFBFVCGTCV7QVTBV"
}

Note: The correlationId can be used whensearching audit records.

Copy

Sample Response for PKI

{"results": [{
   "device": {
      "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
      "id": "13470",
      "externalId": "57585339152211881377412553084082664131",
      "meta": {
         "resourceType": "Device",
         "created": "2020-07-28T23:08:13Z",
         "location": "https://[base-server-url]/scim/tenant/v2/Device/13470",
         "version": "1"
      },
      "type": "DT_SCPKI",
      "status": {
         "status": "ACTIVE",
         "active": true,
         "expiryDate": "2042-09-13T12:51:41Z",
         "startDate": "2012-09-13T12:41:42Z"
      }
   },
   "result": 101,
   "reason": "Imported Token"
}]}

Replace a Device

[PUT] /Device/{id}

Accept: application/scim+json

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.

Updatable attributes:

status.status
status.startDate
status.expiryDate
owner.display (user.externalId)
owner.value (user.id)

Current Status	Possible Transition
PENDING	ACTIVE
ACTIVE	SUSPENDED, REVOKED
SUSPENDED	ACTIVE, REVOKED
REVOKED	TERMINATED

Note:

If owner.value or owner.display is empty, the device will be unassigned from a user.
If owner.value or owner.display is not empty, the device will be assigned to the indicated user.
If the owner section is not indicated, the ownership is not modified.

Copy

Sample Request URI to assign a device

[PUT] /scim/{tenant}/v2/Device/12345

Copy

Sample Request to assign the device to a user and change its status from PENDING to ACTIVE

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
    "status": {
        "status": "ACTIVE"
    },
    "owner": {
        "display": "jdoe"
    }
}

Copy

Sample Response for assign device

{
   "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
   "id": "11348",
   "externalId": "myExternalId10",
   "meta":    {
      "resourceType": "Device",
      "created": "2017-11-20T16:58:33Z",
      "location": "https://[base-server-url]/scim/tenant/v2/Device/11348",
      "version": "1"
   },
   "type": "DT_TDSV4",
   "status":    {
      "status": "ACTIVE",
      "active": true,
      "expiryDate": "2019-06-12T12:46:58Z",
      "startDate": "2017-06-12T12:46:58Z"
   },
   "owner":    {
      "type": "User",
      "display": "jdoe",
      "value": "11288",
      "$ref": "https://[base-server-url]/scim/tenant/v2/Users/11288"
   }
}

Copy

Sample Request URI to unassign a device

[PUT] /scim/{tenant}/v2/Device/12345

Copy

Sample Request to change the status from ACTIVE to REVOKED and unassign the device from the user

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
    "status": {
        "status": "REVOKED"
    },
    "owner": {
        "value": ""
    }
}

Copy

Sample Response for unassign a device

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
    "id": "11348",
    "externalId": "myExternalId10",
    "meta": {
        "resourceType": "Device",
        "created": "2017-11-20T16:58:33Z",
        "location": "https://[base-server-url]/scim/tenant/v2/Device/11348",
        "version": "1"
    },
    "type": "DT_TDSV4",
    "status": {
        "status": "REVOKED",
        "active": false,
        "expiryDate": "2019-06-12T12:46:58Z",
        "startDate": "2017-06-12T12:46:58Z"
    }
}

Search for Devices

Supported search filter criteria are:

SCIM Attribute	Operators supported	Comments
id	eq
externalId	eq, co, sw, ew
type	eq
status.status	eq	Requires 'type' to be specified in the filter
status.expiryDate	eq, gt, lt
owner.value	eq

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Device/.search

Copy

Sample Request

[POST] /scim/{tenant}/v2/Device/.search
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "type eq DT_TDSV4",
    "startIndex": 0,
    "count": 100
}

Where:

The filter attribute can be used to reduce the number of records you want to see.

You can use the and operator within the filters.
The following attributes can be used for a paginated search:
- count can be used to limit the size of the search results
- startIndex specifies the index of the first result returned (where 0 will returned the same paginated result as 1)
The result will contain a totalResults attribute to allow you to compute the number of pages.

Important:
The maximum number of rows returned per request is 100, even if you specify a higher count value. Therefore, for lists that are longer than 100 elements, it is mandatory for you to paginate the results.

For further information, see Searching with the SCIM API.

Delete a Device

All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:

Copy

Delete entity

DELETE https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/{id}

Accept: application/scim+json

Copy

Sample Response

HTTP/1.1 204 No content

Actions on Device

Automatic Counter Resynchronization

[POST] /Device/{id}

Accept: application/scim+json

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Device/10588

Copy

Sample Request using AUTO-SYNCH and set OTP to the current OTP

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "AUTO-SYNCH",
        "attributes": [{
                "name": "OTP",
                "value": "20571257"
            }
        ]
    }
}

Copy

Sample Response

HTTP 204 NoContent

Manual Counter Resynchronization

POST /Device/{id}

Accept: application/scim+json

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Device/10588

Copy

Sample Request using SYNCH-COUNTER and set COUNTER to the current counter value

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
 
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "SYNCH-COUNTER",
        "attributes": [
            {
              "name": "COUNTER",
              "value": "776083399"
            }
        ]}
}

Copy

Sample Response

HTTP 204 NoContent

PIN Unlock

POST /Device/{id}

Accept: application/scim+json

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Device/10589

Copy

Sample Request using PIN-UNLOCK and set attribute CHALLENGE with the challenge displayed on the device

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "PIN-UNLOCK",
        "attributes": [{
                "name": "CHALLENGE",
                "value": "20571256"
            }
        ]
    }
}

Copy

Sample Response

{
    "code": "71176075"
}