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 AS. 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 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/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