Devices

The Okta Devices API provides a centralized integration platform to fetch and manage device information. Okta administrators can use these APIs to manage workforce identity Device object information.

The Devices API supports the following Device Operations:

  • Get, Delete Device objects.
  • Perform lifecycle transitions on the Device objects. Device lifecycle is defined as transitions of the Device Status by the associated operations. The Device object follows a predefined lifecycle transition flow. Device Lifecycle operations are idempotent and its calls are synchronous.

The Devices API supports the following Authorization Schemes:

Note: For devices to enroll in Okta and show up in the Devices API, the following actions are required:

  1. Admins - Enable Okta FastPass. See Enable FastPass
  2. End users with existing mobile Okta Verify enrollments - After you upgrade your org to Okta Identity Engine, direct end users with existing Okta Verify enrollments to use FastPass.

Note: End users with a new enrollment in Okta Verify on an Okta Identity Engine org have a device record created in the device inventory by default. See Device Registration, Login Using Okta Verify.

List all Devices
Identity Engine
OAuth 2.0: okta.devices.read

Lists all devices with pagination support. 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 flows—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.

Request
query Parameters
after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination for more information.

Example: after=200u3des4afA47rYJu1d7
limit
integer [ 1 .. 200 ]
Default: 200

A limit on the number of objects to return (recommend 20)

Example: limit=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.

Examples:
search=status eq "ACTIVE"
search=lastUpdated gt "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
search=id eq "guo4a5u7JHHhjXrMK0g4"
search=profile.displayName eq "Bob"
search=profile.platform eq "WINDOWS"
search=profile.sid sw "S-1"
expand
string

Includes associated user details and management status for the device in the _embedded attribute

Enum: Description
user

Lists full details for associated users

userSummary

Lists summaries for associated users

Examples:
expand=user
expand=userSummary
Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/devices
Request samples 
Response samples 
application/json
[]
Retrieve a Device
Identity Engine
OAuth 2.0: okta.devices.read
Retrieves a device by deviceId


Request 
path Parameters
deviceId
required
string
id of the device


 
 Example:  guo4a5u7JHHhjXrMK0g4
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/devices/{deviceId}
Request samples 
Response samples 
application/json
{}
Delete a Device
Identity Engine
OAuth 2.0: okta.devices.manage
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.




Request 
path Parameters
deviceId
required
string
id of the device


 
 Example:  guo4a5u7JHHhjXrMK0g4
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/devices/{deviceId}
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": [ ]
}
Activate a Device
Identity Engine
OAuth 2.0: okta.devices.manage
Activates a Device by setting its status to ACTIVE by deviceId.
Activated devices are used to create and delete Device user links.


Request 
path Parameters
deviceId
required
string
id of the device


 
 Example:  guo4a5u7JHHhjXrMK0g4
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/devices/{deviceId}/lifecycle/activate
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": [ ]
}
Deactivate a Device
Identity Engine
OAuth 2.0: okta.devices.manage
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.
    • 



Request 
path Parameters
deviceId
required
string
id of the device


 
 Example:  guo4a5u7JHHhjXrMK0g4
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/devices/{deviceId}/lifecycle/deactivate
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": [ ]
}
Suspend a Device
Identity Engine
OAuth 2.0: okta.devices.manage
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.




Request 
path Parameters
deviceId
required
string
id of the device


 
 Example:  guo4a5u7JHHhjXrMK0g4
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/devices/{deviceId}/lifecycle/suspend
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": [ ]
}
Unsuspend a Device
Identity Engine
OAuth 2.0: okta.devices.manage
Unsuspends a Device by returning its status to ACTIVE.




Note: Only devices with a SUSPENDED status can be unsuspended.




Request 
path Parameters
deviceId
required
string
id of the device


 
 Example:  guo4a5u7JHHhjXrMK0g4
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/devices/{deviceId}/lifecycle/unsuspend
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": [ ]
}
List all Users for a Device
Identity Engine
OAuth 2.0: okta.devices.read
Lists all Users for a Device by deviceId


Request 
path Parameters
deviceId
required
string
id of the device


 
 Example:  guo4a5u7JHHhjXrMK0g4
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/devices/{deviceId}/users
Request samples 
Response samples 
application/json
[]