Device Posture Checks

The Device Posture Checks API provides operations to manage custom device posture checks for use in device assurance policies in your organization.

List all device posture checks
Early AccessIdentity Engine
OAuth 2.0:
okta.devicePostureChecks.read

Lists all device posture checks

Responses

200

403

Forbidden

429

Too Many Requests

get/api/v1/device-posture-checks

Request samples

Response samples

application/json

[{"createdBy": "00u217pyf72CdUrBt1c5",
"createdDate": "2019-10-02T18:03:07.000Z",
"description": "Query macOS devices to check if firewall is enabled",
"id": "dch3m8o4rWhwReDeM1c5",
"lastUpdate": "2019-10-02T18:03:07.000Z",
"lastUpdatedBy": "00u217pyf72CdUrBt1c5",
"mappingType": "CHECKBOX",
"name": "Device posture check macOS",
"platform": "MACOS",
"query": "SELECT CASE WHEN global_state = 0 THEN 0 ELSE 1 END AS firewall_enabled FROM  alf;",
"remediationSettings": {"link": {"defaultUrl": "https://help.okta.com/eu/en-us/content/topics/end-user/ov-device-health-macos.htm",
"customUrl": "example.myremediationurl.com/docs"
},
"message": {"defaultI18nKey": "macos.firewall.enabled.remediation.message",
"customText": "It is our company policy that all devices must have a firewall enabled."
}
},
"type": "BUILTIN",
"variableName": "macOSFirewall",
"_links": {"self": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"templated": true,
"type": "string"
}
}
}
]

Create a device posture check
Early Access
OAuth 2.0:
okta.devicePostureChecks.manage

Creates a device posture check

Request

Request Body schema: application/json
required

description

string

Description of the device posture check

mappingType

string (DevicePostureChecksMappingType)

Represents how the device posture check is rendered in device assurance policies

Enum: "CHECKBOX" "TEXTBOX"

name

string

Display name of the device posture check

platform

string (DevicePostureChecksPlatform)

Enum: "MACOS" "WINDOWS"

query

string

OSQuery for the device posture check

object (DevicePostureChecksRemediationSettings)

Represents the remediation instructions shown to the end user when the device posture check fails

object

defaultUrl	string Default URL for the link. This property is only relevant if type is set to `BUILTIN`. If type is set to `CUSTOM`, this field is ignored.
customUrl	string Custom URL for the link

object

defaultI18nKey	string Default i18n key for the message. This property is only relevant if type is set to `BUILTIN`. If type is set to `CUSTOM`, this field is ignored.
customText	string Custom text for the message

type

string (DevicePostureChecksType)

Enum: "BUILTIN" "CUSTOM"

variableName

string

Unique name of the device posture check

Responses

200

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/device-posture-checks

Request samples

application/json

{"name": "Device posture check macOS",
"description": "Query macOS devices to check if firewall is enabled",
"variableName": "macOSFirewall",
"platform": "MACOS",
"type": "CUSTOM",
"mappingType": "CHECKBOX",
"query": "SELECT CASE WHEN global_state = 0 THEN 0 ELSE 1 END AS firewall_enabled FROM alf;",
"remediationSettings": {"message": {"defaultI18nKey": null,
"customText": "It is our company policy that all devices must have a firewall enabled."
},
"link": {"defaultUrl": null,
"customUrl": "example.myremediationurl.com/docs"
}
}
}

Response samples

application/json

{"id": "dch3m8o4rWhwReDeM1c5",
"name": "Device posture check macOS",
"lastUpdate": "2022-01-01T00:00:00.000Z",
"createdUpdate": "2022-01-01T00:00:00.000Z",
"lastUpdatedBy": "00u217pyf72CdUrBt1c5",
"createdBy": "00u217pyf72CdUrBt1c5",
"description": "Query macOS devices to check if firewall is enabled",
"variableName": "macOSFirewall",
"query": "SELECT CASE WHEN global_state = 0 THEN 0 ELSE 1 END AS firewall_enabled FROM  alf;",
"platform": "MACOS",
"type": "CUSTOM",
"mappingType": "CHECKBOX",
"remediationSettings": {"message": {"defaultI18nKey": null,
"customText": "It is our company policy that all devices must have a firewall enabled."
},
"link": {"defaultUrl": null,
"customUrl": "example.myremediationurl.com/docs"
}
},
"_links": {"self": {"href": "https://your-subdomain.okta.com/api/v1/device-posture-checks/dch3m8o4rWhwReDeM1c5",
"hints": {"allow": ["DELETE",
"GET",
"PUT"
]
}
}
}
}

List all default device posture checks
Early Access
OAuth 2.0:
okta.devicePostureChecks.read

Lists all default device posture checks. Default device posture checks are defined by Okta. Their type will always be BUILTIN.

Responses

200

403

Forbidden

429

Too Many Requests

get/api/v1/device-posture-checks/default

Request samples

Response samples

application/json

[{"createdBy": "00u217pyf72CdUrBt1c5",
"createdDate": "2019-10-02T18:03:07.000Z",
"description": "Query macOS devices to check if firewall is enabled",
"id": "dch3m8o4rWhwReDeM1c5",
"lastUpdate": "2019-10-02T18:03:07.000Z",
"lastUpdatedBy": "00u217pyf72CdUrBt1c5",
"mappingType": "CHECKBOX",
"name": "Device posture check macOS",
"platform": "MACOS",
"query": "SELECT CASE WHEN global_state = 0 THEN 0 ELSE 1 END AS firewall_enabled FROM  alf;",
"remediationSettings": {"link": {"defaultUrl": "https://help.okta.com/eu/en-us/content/topics/end-user/ov-device-health-macos.htm",
"customUrl": "example.myremediationurl.com/docs"
},
"message": {"defaultI18nKey": "macos.firewall.enabled.remediation.message",
"customText": "It is our company policy that all devices must have a firewall enabled."
}
},
"type": "BUILTIN",
"variableName": "macOSFirewall",
"_links": {"self": {"hints": {"allow": ["DELETE"
]
},
"href": "string",
"name": "string",
"templated": true,
"type": "string"
}
}
}
]

Retrieve a device posture check
Early AccessIdentity Engine
OAuth 2.0:
okta.devicePostureChecks.read

Retrieves a device posture check by postureCheckId

Request

path Parameters

postureCheckId

required

string

ID of the device posture check

Responses

200

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/device-posture-checks/{postureCheckId}

Request samples

Response samples

application/json

{"id": "dch3m8o4rWhwReDeM1c5",
"name": "Device posture check macOS",
"lastUpdate": "2022-01-01T00:00:00.000Z",
"createdUpdate": "2022-01-01T00:00:00.000Z",
"lastUpdatedBy": "00u217pyf72CdUrBt1c5",
"createdBy": "00u217pyf72CdUrBt1c5",
"description": "Query macOS devices to check if firewall is enabled",
"variableName": "macOSFirewall",
"query": "SELECT CASE WHEN global_state = 0 THEN 0 ELSE 1 END AS firewall_enabled FROM  alf;",
"platform": "MACOS",
"type": "CUSTOM",
"mappingType": "CHECKBOX",
"remediationSettings": {"message": {"defaultI18nKey": null,
"customText": "It is our company policy that all devices must have a firewall enabled."
},
"link": {"defaultUrl": null,
"customUrl": "example.myremediationurl.com/docs"
}
},
"_links": {"self": {"href": "https://your-subdomain.okta.com/api/v1/device-posture-checks/dch3m8o4rWhwReDeM1c5",
"hints": {"allow": ["DELETE",
"GET",
"PUT"
]
}
}
}
}

Replace a device posture check
Early Access
OAuth 2.0:
okta.devicePostureChecks.manage

Replaces a device posture check by postureCheckId

Request

path Parameters

postureCheckId

required

string

ID of the device posture check

Request Body schema: application/json
required

description

string

Description of the device posture check

mappingType

string (DevicePostureChecksMappingType)

Represents how the device posture check is rendered in device assurance policies

Enum: "CHECKBOX" "TEXTBOX"

name

string

Display name of the device posture check

platform

string (DevicePostureChecksPlatform)

Enum: "MACOS" "WINDOWS"

query

string

OSQuery for the device posture check

object (DevicePostureChecksRemediationSettings)

Represents the remediation instructions shown to the end user when the device posture check fails

object

defaultUrl	string Default URL for the link. This property is only relevant if type is set to `BUILTIN`. If type is set to `CUSTOM`, this field is ignored.
customUrl	string Custom URL for the link

object

defaultI18nKey	string Default i18n key for the message. This property is only relevant if type is set to `BUILTIN`. If type is set to `CUSTOM`, this field is ignored.
customText	string Custom text for the message

type

string (DevicePostureChecksType)

Enum: "BUILTIN" "CUSTOM"

variableName

string

Unique name of the device posture check

Responses

200

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/device-posture-checks/{postureCheckId}

Request samples

application/json

{"name": "Device posture check macOS",
"description": "Query macOS devices to check if firewall is enabled",
"variableName": "macOSFirewall",
"platform": "MACOS",
"type": "CUSTOM",
"mappingType": "CHECKBOX",
"query": "SELECT CASE WHEN global_state = 0 THEN 0 ELSE 1 END AS firewall_enabled FROM alf;",
"remediationSettings": {"message": {"defaultI18nKey": null,
"customText": "It is our company policy that all devices must have a firewall enabled."
},
"link": {"defaultUrl": null,
"customUrl": "example.myremediationurl.com/docs"
}
}
}

Response samples

application/json

{"id": "dch3m8o4rWhwReDeM1c5",
"name": "Device posture check macOS",
"lastUpdate": "2022-01-01T00:00:00.000Z",
"createdUpdate": "2022-01-01T00:00:00.000Z",
"lastUpdatedBy": "00u217pyf72CdUrBt1c5",
"createdBy": "00u217pyf72CdUrBt1c5",
"description": "Query macOS devices to check if firewall is enabled",
"variableName": "macOSFirewall",
"query": "SELECT CASE WHEN global_state = 0 THEN 0 ELSE 1 END AS firewall_enabled FROM  alf;",
"platform": "MACOS",
"type": "CUSTOM",
"mappingType": "CHECKBOX",
"remediationSettings": {"message": {"defaultI18nKey": null,
"customText": "It is our company policy that all devices must have a firewall enabled."
},
"link": {"defaultUrl": null,
"customUrl": "example.myremediationurl.com/docs"
}
},
"_links": {"self": {"href": "https://your-subdomain.okta.com/api/v1/device-posture-checks/dch3m8o4rWhwReDeM1c5",
"hints": {"allow": ["DELETE",
"GET",
"PUT"
]
}
}
}
}

Delete a device posture check
Early AccessIdentity Engine
OAuth 2.0:
okta.devicePostureChecks.manage

Deletes a device posture check by postureCheckId. You can't delete the device posture check if it's used in a device assurance policy.

Request

path Parameters

postureCheckId

required

string

ID of the device posture check

Responses

204

No Content

403

Forbidden

404

Not Found

409

Conflict

429

Too Many Requests

delete/api/v1/device-posture-checks/{postureCheckId}

Request samples

Response samples

application/json

{"errorCode": "E0000006",
"errorSummary": "You do not have permission to perform the requested action",
"errorLink": "E0000006",
"errorId": "sampleNUSD_8fdkFd8fs8SDBK",
"errorCauses": [ ]
}

Social
CONTACT & LEGAL
MORE INFORMATION
okta.com
Products, case studies, resources
Help Center
Knowledgebase, roadmaps, and more
Trust
System status, security, compliance

Device Posture Checks

List all device posture checksEarly AccessIdentity EngineOAuth 2.0: okta.devicePostureChecks.read

Create a device posture checkEarly AccessOAuth 2.0: okta.devicePostureChecks.manage

Request Body schema: application/jsonrequired

List all default device posture checksEarly AccessOAuth 2.0: okta.devicePostureChecks.read

Retrieve a device posture checkEarly AccessIdentity EngineOAuth 2.0: okta.devicePostureChecks.read

path Parameters

Replace a device posture checkEarly AccessOAuth 2.0: okta.devicePostureChecks.manage

path Parameters

Request Body schema: application/jsonrequired

Delete a device posture checkEarly AccessIdentity EngineOAuth 2.0: okta.devicePostureChecks.manage

path Parameters

List all device posture checks
Early AccessIdentity Engine
OAuth 2.0:
okta.devicePostureChecks.read

Create a device posture check
Early Access
OAuth 2.0:
okta.devicePostureChecks.manage

Request Body schema: application/json
required

List all default device posture checks
Early Access
OAuth 2.0:
okta.devicePostureChecks.read

Retrieve a device posture check
Early AccessIdentity Engine
OAuth 2.0:
okta.devicePostureChecks.read

Replace a device posture check
Early Access
OAuth 2.0:
okta.devicePostureChecks.manage

Request Body schema: application/json
required

Delete a device posture check
Early AccessIdentity Engine
OAuth 2.0:
okta.devicePostureChecks.manage