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.
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 |
|
CREATE |
|
REPLACE |
|
DELETE |
|
SEARCH |
|
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.
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
}
]
}
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
}
]
}
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
}
]
}
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
}]
}
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
}
]
}
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 |
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.
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" : []
}
]
}
Delete a Device Provision
All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:
Accept: application/scim+json