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.
See also the Get and Set OATH Device Counter tutorial.
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.
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 |
POST |
Action |
/scim/{tenant}/v2/Device/{id}:(String) |
Perform an action on a device |
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 |
|
CREATE |
|
REPLACE |
|
DELETE |
|
Create a Device
[POST] /Device
Accept: application/scim+json
Status can be:
-
ACTIVE
-
PENDING
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"
}
}
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}
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
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
[POST] /Device/.import
The parameters are:
Parameter | Description |
---|---|
|
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) |
|
Object representing the binding between the deviceType and the associated credentialType to import |
|
Encryption key (in hexadecimal string format) |
|
Resynchronization window |
|
Status of the device after import (ACTIVE or PENDING) |
|
(Optional) Reference of the user to who the device should be assigned If owner is specified, either value or display must also be specified:
|
|
(Optional) Reference of the authentication policy for creating the user authenticator If policy is specified, the owner must also be specified:
|
|
Binary of the file to import, encoded in base64 |
|
Indicates if the import is synchronous or asynchronous |
|
(Optional) If no correlationId is specified, a random one is generated. The correlationId will appear in all audit records for this import. |
|
(Optional) Can be used to define a "valid from" date for devices and credentials |
|
(Optional) Can be used to define a "valid to" date for devices and credentials |
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
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).
Example of a mapping for a .pskc file containing only the TOTP algo
"mapping": [{
"deviceType": "DT_MIN_OT",
"algo": "TOTP"
}]
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"
}]
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"
}]
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
}
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:
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"
}
]
}
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"
}
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
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 |
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.
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"
}
}
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"
}
}
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": ""
}
}
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 |
Requires 'type' to be specified in the filter |
status.startDate |
eq |
Requires 'type' to be specified in the filter |
owner.value |
eq |
|
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.
Note: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:
Accept: application/scim+json
Actions on Device
Automatic Counter Resynchronization
[POST] /Device/{id}
Accept: application/scim+json
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"
}
]
}
}
Manual Counter Resynchronization
POST /Device/{id}
Accept: application/scim+json
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"
}
]}
}
PIN Unlock
POST /Device/{id}
Accept: application/scim+json
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"
}
]
}
}