devices

Creates, updates, deletes, gets or lists a devices resource.

Overview

Name	devices
Type	Resource
Id	okta.devices.devices

Fields

The following fields are returned by SELECT queries:

list_devices

Name	Datatype	Description
id	string	Unique key for the device
_embedded	object	List of associated users for the device if the expand=user query parameter is specified in the request. Use expand=userSummary to get only a summary of each associated user for the device.
_links	object	Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
created	string (date-time)	Timestamp when the device was created
lastUpdated	string (date-time)	Timestamp when the device record was last updated. Updates occur when Okta collects and saves device signals during authentication, and when the lifecycle state of the device changes.
profile	object
resourceAlternateId	string
resourceDisplayName	object	Display name of the device
resourceId	string	Alternate key for the id
resourceType	string	(default: UDDevice)
status	string	The state object of the device

get_device

Name	Datatype	Description
id	string	Unique key for the device
_links	object	Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
created	string (date-time)	Timestamp when the device was created
lastUpdated	string (date-time)	Timestamp when the device record was last updated. Updates occur when Okta collects and saves device signals during authentication, and when the lifecycle state of the device changes.
profile	object
resourceAlternateId	string
resourceDisplayName	object	Display name of the device
resourceId	string	Alternate key for the id
resourceType	string	(default: UDDevice)
status	string	The state object of the device

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_devices	select	subdomain	after, limit, search, expand	Lists all devices with pagination support. >Note: To list all devices enrolled by a user, use the List all devices endpoint in the User Resources API. You can return a subset of devices that match a supported search criteria using the search query parameter. Searches for devices based on the properties specified in the search parameter conforming SCIM filter specifications (case-insensitive). This data is eventually consistent. The API returns different results depending on specified queries in the request. Empty list is returned if no objects match search request. > Note: Listing devices with search should not be used as a part of any critical flow, such as authentication or updates, to prevent potential data loss. search results may not reflect the latest information, as this endpoint uses a search index which may not be up-to-date with recent updates to the object. Don't use search results directly for record updates, as the data might be stale and therefore overwrite newer data, resulting in data loss. Use an id lookup for records that you update to ensure your results contain the latest data. This operation requires URL encoding. For example, search=profile.displayName eq "Bob" is encoded as search=profile.displayName%20eq%20%22Bob%22.
get_device	select	subdomain		Retrieves a device by deviceId
delete_device	delete	subdomain		Deletes (permanently) a device by deviceId if it has a status of DEACTIVATED. You can transition the device to DEACTIVATED status using the Deactivate a Device endpoint. This request is destructive and deletes all of the profile data related to the device. Once deleted, device data can't be recovered. However, reenrollment creates a new device record. > Note: Attempts to delete a device that isn't in a DEACTIVATED state raise an error.
activate_device	exec	subdomain		Activates a device by setting its status to ACTIVE by deviceId. Activated devices are used to create and delete device user links.
deactivate_device	exec	subdomain		Deactivates a device by setting its status to DEACTIVATED by deviceId. Deactivation causes a device to lose all device user links. Set the device status to DEACTIVATED before deleting it. > Note: When deactivating a Device, keep in mind the following: - Device deactivation is a destructive operation for device factors and client certificates. Device reenrollment using Okta Verify allows end users to set up new factors on the device. - Device deletion removes the device record from Okta. Reenrollment creates a new device record.
suspend_device	exec	subdomain		Suspends a device by setting its status to SUSPENDED. Use suspended devices to create and delete device user links. You can only unsuspend or deactivate suspended devices. > Note: SUSPENDED status is meant to be temporary, so it isn't destructive.
unsuspend_device	exec	subdomain		Unsuspends a device by returning its status to ACTIVE. >Note: Only devices with a SUSPENDED status can be unsuspended.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
subdomain	string	The domain of your organization. This can be a provided subdomain of an official okta domain (okta.com, oktapreview.com, etc) or one of your configured custom domains. (default: my-org)
after	string
expand	string	Includes associated user details and management status for the device in the _embedded attribute
limit	integer	A limit on the number of objects to return (recommend 20)
search	string	A SCIM filter expression that filters the results. Searches include all device profile properties and the device id, status, and lastUpdated properties. Searches for devices can be filtered by the contains (co) operator. You can only use co with these select device profile attributes: profile.displayName, profile.serialNumber, profile.imei, profile.meid, profile.udid, and profile.sid. See Operators.

SELECT examples

list_devices

Lists all devices with pagination support.

>Note: To list all devices enrolled by a user, use the List all devices endpoint in the User Resources API.

You can return a subset of devices that match a supported search criteria using the search query parameter.
Searches for devices based on the properties specified in the search parameter conforming SCIM filter specifications (case-insensitive). This data is eventually consistent. The API returns different results depending on specified queries in the request. Empty list is returned if no objects match search request.
> Note: Listing devices with search should not be used as a part of any critical flow, such as authentication or updates, to prevent potential data loss. search results may not reflect the latest information, as this endpoint uses a search index which may not be up-to-date with recent updates to the object.

Don't use search results directly for record updates, as the data might be stale and therefore overwrite newer data, resulting in data loss.

Use an id lookup for records that you update to ensure your results contain the latest data.

This operation requires URL encoding. For example, search=profile.displayName eq "Bob" is encoded as search=profile.displayName%20eq%20%22Bob%22.

SELECT
id,
_embedded,
_links,
created,
lastUpdated,
profile,
resourceAlternateId,
resourceDisplayName,
resourceId,
resourceType,
status
FROM okta.devices.devices
WHERE subdomain = '{{ subdomain }}' -- required
AND after = '{{ after }}'
AND limit = '{{ limit }}'
AND search = '{{ search }}'
AND expand = '{{ expand }}'
;

get_device

Retrieves a device by deviceId

SELECT
id,
_links,
created,
lastUpdated,
profile,
resourceAlternateId,
resourceDisplayName,
resourceId,
resourceType,
status
FROM okta.devices.devices
WHERE subdomain = '{{ subdomain }}' -- required
;

DELETE examples

delete_device

Deletes (permanently) a device by deviceId if it has a status of DEACTIVATED. You can transition the device to DEACTIVATED status using the Deactivate a Device endpoint.
This request is destructive and deletes all of the profile data related to the device. Once deleted, device data can't be recovered. However, reenrollment creates a new device record.
> Note: Attempts to delete a device that isn't in a DEACTIVATED state raise an error.

DELETE FROM okta.devices.devices
WHERE subdomain = '{{ subdomain }}' --required
;

Lifecycle Methods

activate_device

Activates a device by setting its status to ACTIVE by deviceId.
Activated devices are used to create and delete device user links.

EXEC okta.devices.devices.activate_device 
@subdomain='{{ subdomain }}' --required
;

deactivate_device

Deactivates a device by setting its status to DEACTIVATED by deviceId.
Deactivation causes a device to lose all device user links. Set the device status to DEACTIVATED before deleting it.
> Note: When deactivating a Device, keep in mind the following:
- Device deactivation is a destructive operation for device factors and client certificates. Device reenrollment using Okta Verify allows end users to set up new factors on the device.
- Device deletion removes the device record from Okta. Reenrollment creates a new device record.

EXEC okta.devices.devices.deactivate_device 
@subdomain='{{ subdomain }}' --required
;

suspend_device

Suspends a device by setting its status to SUSPENDED.
Use suspended devices to create and delete device user links. You can only unsuspend or deactivate suspended devices.
> Note: SUSPENDED status is meant to be temporary, so it isn't destructive.

EXEC okta.devices.devices.suspend_device 
@subdomain='{{ subdomain }}' --required
;

unsuspend_device

Unsuspends a device by returning its status to ACTIVE.
>Note: Only devices with a SUSPENDED status can be unsuspended.

EXEC okta.devices.devices.unsuspend_device 
@subdomain='{{ subdomain }}' --required
;