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.

Note: The API version supported by ActivID AS 8.6 is 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.

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

  • 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 when searching 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

Requires 'type' to be specified in the filter

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.

    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:

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"
}