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 ActivID Appliance. This is an entity that represents a future device, while the registration invitation is sent to the end user.

For further information, see Deploying the Push-Based Validation Solution, specifically Register a Device for Validation with Push.

Note: The API version supported by ActivID Appliance 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/Provision/{id}.(String)	Retrieve a device provision
GET	Create	/scim/{tenant}/v2/Provision/	Create a new device provision
POST	Search	/scim/{tenant}/v2/Provision/.search	Search for device provisions
POST	Replace	/scim/{tenant}/v2/Provision/{id}.(String)	Fully replace a known device provision (usually triggers actions server-side)
POST	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
        }
    ]
}

Copy

Sample Request for Offline Activation (Time-Based)

[POST] /scim/{tenant}/v2/Device/Provision
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"deviceType": "DT_APPR_OT",
	"owner": {
		"value": "11066"
	},
	"attributes": [{
		"name": "AUTH_TYPE",
		"value": "AT_EMPOTP",
		"readOnly": false
		}
	]
}

Copy

Sample Response for Offline Activation (Time-Based)

HTTP/1.1 201 Created
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"id": "1",
	"meta":    {
		"resourceType": "Provision",
		"created": "2021-09-16T13:20:51Z",
		"location": "https://[base-server-url]/scim/tenant/v2/Device/Provision/1",
		"version": "1"
	},
	"deviceType": "DT_APPR_OT",
	"status":    {
		"status": "PROCESSED",
		"active": false
	},
	"owner":    {
		"type": "User",
		"display": "aaaa1000000",
		"value": "11066",
		"$ref": "https://[base-server-url]/scim/tenant/v2/Users/11066"
	},
	"attributes": [   {
		"name": "PROV_MSG",
		"type": "string",
		"value": "otpauth://totp/HID%20Global:aaaa1000000?secret=2J4DYTYSNHUCGCUY3QZ2YI4UCDQXFSGE&issuer=HID%20Global&algorithm=SHA1&digits=6&period=30&pinmode=pin&lockpolicy=delay&initialdelay=2&maxcountervalue=6",
		"readOnly": false
	}]
}

Copy

Sample Request for Offline Activation (Event-Based)

[POST] /scim/{tenant}/v2/Device/Provision
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"deviceType": "DT_APPR_OE",
	"owner": {
		"value": "11066"
	},
	"attributes": [{
		"name": "AUTH_TYPE",
		"value": "AT_EMPOTP",
		"readOnly": false
		}
	]
}

Copy

Sample Response for Offline Activation (Event-Based)

HTTP/1.1 201 Created
{
	"schemas": ["urn:hid:scim:api:idp:2.0:Provision"],
	"id": "1",
	"meta":    {
		"resourceType": "Provision",
		"created": "2021-09-16T13:09:29Z",
		"location": "https://[base-server-url]/scim/tenant/v2/Device/Provision/1",
		"version": "1"
	},
	"deviceType": "DT_APPR_OE",
	"status":    {
		"status": "PROCESSED",
		"active": false
	},
	"owner":    {
		"type": "User",
		"display": "aaaa1000000",
		"value": "11066",
		"$ref": "https://[base-server-url]/scim/tenant/v2/Users/11066"
	},
	"attributes": [   {
		"name": "PROV_MSG",
		"type": "string",
		"value": "otpauth://hotp/HID%20Global:aaaa1000000?secret=XYHJUYR3Y3GI7BTHEDCNOB4CSDNXFAJE&issuer=HID%20Global&algorithm=SHA1&digits=6&counter=1474460590&pinmode=pin&lockpolicy=delay&initialdelay=2&maxcountervalue=6",
		"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