Device Provision REST API

The Device/Provision endpoint allows supporting the multi-step HID Approve activation workflow from sending an invitation to a user to register their device until authentication credentials are created asynchronously in HID Authentication Service. This is an entity that represents a future device, while the registration invitation is sent to the end user.

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/Provision/{id}.(String)	Retrieve a device provision
POST	Create	/scim/{tenant}/v2/Provision/	Create a new device provision
POST	Search	/scim/{tenant}/v2/Provision/.search	Search for device provisions
PUT	Replace	/scim/{tenant}/v2/Provision/{id}.(String)	Fully replace a known device provision (usually triggers actions server-side)
DELETE	Delete	/scim/{tenant}/v2/Provision/{id}.(String)	Delete a known device provision

Required Permissions

Function	Required Permissions
GET	Read device issuance request
CREATE	Read user details Create device issuance request
REPLACE	Read device issuance request Read user details Create device issuance request
DELETE	Delete device
SEARCH	Read device issuance request Read user details

Get a Device Provision

This API is used internally by the HID Approve SDK to provide support for the HID Approve Activation workflow. It is not intended to be used in any other context.

Create a Device Provision

[POST] /Device/Provision

Accept: application/scim+json

This is the first step to request an HID Approve™ activation.

Copy

Sample Request URI

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

Copy

Sample Request for Online Activation

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
    "deviceType": "DT_TDSV4",
    "description": "did=11333,url=[base-server-url]/tenant,pch=CH_TDSPROV,pth=AT_TDSOOB,pct=CT_TDSOOB,pdt=DT_TDSOOB,mod=GEN,sec=",
    "owner": {
        "value" : "11047"
    },
    "attributes": [{
            "name": "AUTH_TYPE",
            "value": "AT_SMK",
            "readOnly": false
        }
    ]
}

Copy

Sample Response for Online Activation

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
    "id" : "11040",
    "meta": {
        "resourceType": "Provision",
        "created": "2017-06-12T13:08:56Z",
        "location": "https://[base-server-url]/scim/tenant/v2/Device/Provision/11040",
        "version": "1"
    },
    "deviceType": "DT_TDSV4",
    "status": {
        "status": "UNPROCESSED",
        "active": false
    },
    "owner": {
        "type": "User",
        "display" : "myUser",
        "value" : "11047",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Users/11047"
    },
    "attributes": [{
            "name": "PROV_MSG",
            "type": "string",
            "value": "{\"ver\":\"v5\",\"url\":\"[base-server-url]/tenant\",\"uid\":\"aro1\",\"did\":\"11333\",\"dty\":\"DT_TDSV4\",\"pch\":\"CH_TDSPROV\",\"pth\":\"AT_TDSOOB\",\"sec\":\"\",\"pss\":\"UE9CSkcxNElBOA==\"}",
            "readOnly": false
        }
    ]
}

Replace a Device Provision

This API is used internally by the HID Approve SDK to provide support for the HID Approve Activation workflow. It is not intended to be used in any other context.

Search for a Device Provision

[POST] /Device/Provision/.search

Accept: application/scim+json

Supported search criteria are:

SCIM Attribute	Operators supported
deviceType (mandatory)	eq
status.status	eq
owner.value	eq

Copy

Sample Request URI

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

Copy

Sample Request

{
 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
 "filter": "deviceType eq DT_TDSV4 and owner.value eq 11092 and status.status eq UNPROCESSED",
}

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.

Copy

Sample Response

{
    "schemas" : ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults" : 1,
    "resources" : [{
            "schemas" : ["urn:hid:scim:api:idp:2.0:Provision"],
            "id" : "11242",
            "meta" : {
                "resourceType" : "Device",
                "created" : "2016-03-13T23:00:00Z",
                "location" : "https://[base-server-url]/scim/tenant/v2/Device/Provision/11242",
                "version" : "1"
            },
            "deviceType" : "DT_TDS",
            "status" : {
                "status" : "UNPROCESSED",
                "active" : false
            },
            "description" : "pid=11980,pfm=Android,did=11980,dcd=tenant.CH_TDSPROV.AT_TDSOOB.DT_TDS.AT_TDS,url=https://[base-server-url],pth=AT_TDSOOB,pdt=DT_TDSOOB,pct=CT_TDSOOB,pin=134679,mod=GEN,sec=,pss=T1t5dWdFVj0jYA==",
            "owner" : {
                "type" : "User",
                "display" : "userTest",
                "value" : "11914",
                "$ref" : "https://[base-server-url]/scim/tenant/v2/Users/11914"
            },
            "attributes" : []
        }
    ]
}

Note: For further information, see Searching with the SCIM API.

Delete a Device Provision

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