From 161ced384e0505136a5eae5250776ac1a02824e0 Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Tue, 18 Apr 2023 21:13:52 -0400 Subject: [PATCH 1/5] adds content --- .../docs/reference/api/devices/index.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index d146a37828a..c4105e7d296 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -605,6 +605,121 @@ curl -v -X GET \ ] ``` +### List all Users for a Device + + + +Lists all [Users](/docs/reference/api/users/#user-object) for a Device by `deviceId` + +#### Request parameters + +| Parameter | Description | ParamType | DataType | Required | Default | +| --------- | ---------------------------------------------------------- | --------- | -------- | -------- | ------- | +| after | Specifies the pagination cursor for the next page of users | Query | String | FALSE | | +| id | ID of the Device | URL | String | TRUE | | +| limit | Specifies the number of user results in a page | Query | Number | FALSE | 1000 | + +> **Note:** Treat the `after` cursor as an opaque value and obtain it through the next link relation. See [Pagination](/docs/reference/core-okta-api/#pagination). + +> **Note:** If you receive an HTTP 500 status code, you likely exceed the request timeout. Retry your request with a smaller `limit` and page the results. See [Pagination](/docs/reference/core-okta-api/#pagination). + +#### Response parameters + +Array of [Users](/docs/reference/api/users/#user-object) + +#### Request example + +```bash +curl -v -X GET \ +-H "Accept: application/json" \ +-H "Content-Type: application/json" \ +-H "Authorization: SSWS ${api_token}" \ +"https://${yourOktaDomain}/api/v1/devices/${deviceId}/users?limit=200" +``` + +#### Response example + +```json +[ + { + "created":"2021-08-20T17:13:35.000Z", + "managementStatus":"NOT_MANAGED", + "user":{ + "id":"00u17vh0q8ov8IU881d7", + "status":"ACTIVE", + "created":"2021-08-20T16:08:25.000Z", + "activated":null, + "statusChanged":"2021-08-20T16:39:41.000Z", + "lastLogin":"2023-04-18T17:54:12.000Z", + "lastUpdated":"2021-12-20T18:27:30.000Z", + "passwordChanged":"2021-12-20T18:27:30.000Z", + "type":{ + "id":"oty17vh0n2EHVnbYF1d7" + }, + "profile":{ + "firstName":"Bunk", + "lastName":"Moreland", + "mobilePhone":null, + "secondEmail":null, + "login":"bunk.moreland@example.com", + "email":"bunk.moreland@example.com" + }, + "credentials":{ + "password":{ + }, + "provider":{ + "type":"OKTA", + "name":"OKTA" + } + }, + "_links":{ + "suspend":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/lifecycle/suspend", + "method":"POST" + }, + "schema":{ + "href":"https://{yourOktaDomain}/api/v1/meta/schemas/user/osc17vh0n2EHVnbYF1d7" + }, + "resetPassword":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/lifecycle/reset_password", + "method":"POST" + }, + "forgotPassword":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/credentials/forgot_password", + "method":"POST" + }, + "expirePassword":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/lifecycle/expire_password", + "method":"POST" + }, + "changeRecoveryQuestion":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/credentials/change_recovery_question", + "method":"POST" + }, + "self":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7" + }, + "resetFactors":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/lifecycle/reset_factors", + "method":"POST" + }, + "type":{ + "href":"https://{yourOktaDomain}/api/v1/meta/types/user/oty17vh0n2EHVnbYF1d7" + }, + "changePassword":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/credentials/change_password", + "method":"POST" + }, + "deactivate":{ + "href":"https://{yourOktaDomain}/api/v1/users/00u17vh0q8ov8IU881d7/lifecycle/deactivate", + "method":"POST" + } + } + } + } +] +``` + ### Delete Device From 93e27f3a19d25d921f9d7dc8c9b16162694b6d22 Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Tue, 18 Apr 2023 22:40:03 -0400 Subject: [PATCH 2/5] adds operation to list at top of doc --- packages/@okta/vuepress-site/docs/reference/api/devices/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index c4105e7d296..4d6f844cea6 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -36,6 +36,7 @@ The Devices API has the following Device Identity operations: * [Get Device](#get-device-by-id) * [List Devices](#list-devices) +* [List all Users for a Device](#list-all-users-for-a-device) * [Delete Device](#delete-device) The following Device lifecycle operations: From 9c93ade88624edfac170e31fe3f39d7270d9ba82 Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Thu, 20 Apr 2023 11:51:49 -0400 Subject: [PATCH 3/5] tweaks --- .../@okta/vuepress-site/docs/reference/api/devices/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index 4d6f844cea6..8d0af337899 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -608,7 +608,7 @@ curl -v -X GET \ ### List all Users for a Device - + Lists all [Users](/docs/reference/api/users/#user-object) for a Device by `deviceId` From 85868bad087fe8619335dee93c40fb9bce64dbfb Mon Sep 17 00:00:00 2001 From: brentschaus-okta Date: Wed, 26 Apr 2023 09:47:40 -0400 Subject: [PATCH 4/5] Acrolinxing --- .../docs/reference/api/devices/index.md | 83 ++++++++++--------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index 8d0af337899..9f9e0adbbba 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -17,14 +17,14 @@ The Devices API supports the following **Device Operations**: The Devices API supports the following **Authorization Schemes**: * SSWS - [API tokens](/docs/reference/core-okta-api/#authentication) -* Bearer - [OAuth2.0 and OpenID Connect](/docs/concepts/oauth-openid/) +* Bearer - [OAuth 2.0 and OpenID Connect](/docs/concepts/oauth-openid/) > **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](https://help.okta.com/okta_help.htm?type=oie&id=ext-fp-enable) -> 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](https://help.okta.com/okta_help.htm?type=oie&id=csh-fp-main). +> 1. Admins - enable Okta FastPass. See [Enable Okta FastPass](https://help.okta.com/okta_help.htm?type=oie&id=ext-fp-enable) +> 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 [Okta FastPass](https://help.okta.com/okta_help.htm?type=oie&id=csh-fp-main). > 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](https://help.okta.com/okta_help.htm?type=oie&id=csh-device-registration), [Login Using Okta Verify](https://help.okta.com/okta_help.htm?type=eu&id=ext-ov-user-overview). +See [Device Registration](https://help.okta.com/okta_help.htm?type=oie&id=csh-device-registration), [Log in Using Okta Verify](https://help.okta.com/okta_help.htm?type=eu&id=ext-ov-user-overview). ## Get started @@ -32,7 +32,7 @@ Explore the Devices API: [![Run in Postman](https://run.pstmn.io/button.svg)](ht ## Device operations -The Devices API has the following Device Identity operations: +The Devices API has the following Device identity operations: * [Get Device](#get-device-by-id) * [List Devices](#list-devices) @@ -181,20 +181,20 @@ Content-Type: application/json -Fetches a list of all Devices that are not `DELETED` for your org. Responses are paginated with maximum size of 200. +Fetches a list of all Devices that aren’t `DELETED` for your org. Responses are paginated with maximum size of 200. A subset of Devices can be returned 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. +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. An empty list is returned if no objects match the `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. +> **Note:** Listing devices with `search` shouldn’t be used as a part of any critical flows—such as authentication or updates—to prevent potential data loss. The `search` results may not reflect the latest information, as this endpoint uses a search index that 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: * Supports pagination (to a maximum of 200 results). * Requires [URL encoding](http://en.wikipedia.org/wiki/Percent-encoding). For example, `search=profile.displayName eq "Bob"` is encoded as `search=profile.displayName%20eq%20%22Bob%22`. -Searches include all Device profile properties, as well as the Device `id`, `status` and `lastUpdated` properties. +Searches include all Device profile properties, and the Device `id`, `status` and `lastUpdated` properties. | Search term example | Description | | :---------------------------------------------- | :----------------------------------------------- | @@ -368,7 +368,7 @@ Link: -Permanently deletes a Device that is in `DEACTIVATED` status. The Device can be transitioned to `DEACTIVATED` status using [deactivate](#deactivate-device) API. +Permanently deletes a Device that is in `DEACTIVATED` status. The Device can be transitioned to `DEACTIVATED` status using the [deactivate](#deactivate-device) API. -This deletion is destructive and deletes all the profile data related to the device. Once deleted, device data can't be recovered. A Device that is not in a `DEACTIVATED` state raises an error if Delete operation is attempted. +This deletion is destructive and deletes all the profile data related to the device. Once deleted, device data can't be recovered. A Device that isn’t in a `DEACTIVATED` state raises an error if a delete operation is attempted. #### Permitted OAuth 2.0 scopes `okta.devices.manage` @@ -777,11 +777,11 @@ Content-Type: application/json ##### Error response -Passing an invalid `id` returns a `404 Not Found` status code with error code `E0000007`. +Passing an invalid `id` returns a `404 Not Found` status code with the error code `E0000007`. ## Lifecycle operations -Device lifecycle is defined as transitions of the [Device Status](#device-status) by the associated operations. The Device object follows a predefined lifecycle transition flow. Device Lifecycle operations are idempotent. These are synchronous calls. +Device lifecycle is defined as transitions of the [Device Status](#device-status) by the associated operations. The Device object follows a predefined lifecycle transition flow. Device lifecycle operations are idempotent. These are synchronous calls. * [Activate Device](#activate-device) * [Deactivate Device](#deactivate-device) @@ -848,8 +848,8 @@ Content-Type: application/json #### Error responses -* Passing an invalid `id` returns a `404 Not Found` status code with error code `E0000007`. -* Passing an `id` that is not in the `CREATED` or `DEACTIVATED` status returns a `400 Bad Request` status code with error code `E0000001`. +* Passing an invalid `id` returns a `404 Not Found` status code with the error code `E0000007`. +* Passing an `id` that isn’t in the `CREATED` or `DEACTIVATED` status returns a `400 Bad Request` status code with the error code `E0000001`. ### Deactivate Device @@ -859,9 +859,9 @@ Sets a Device's `status` to `DEACTIVATED`. Deactivation causes a Device to lose > **Important**: > 1. Deactivating a Device is a **destructive** operation for device factors and client certificates. -> 2. Device deactivation renders associated assets—such as device factors and management certificates—unusable. Device re-enrollment via Okta Verify allows end users to setup new +> 2. Device deactivation renders associated assets—such as device factors and management certificates—unusable. Device re-enrollment through Okta Verify allows end users to set up new factors on the device. -> 3. Deletion of the device after deactivation also deletes the device record from Okta. Re-enrollment of Okta Verify creates a new device record. +> 3. Deletion of the device after deactivation also deletes the device record from Okta. Re-enrollment of Okta Verify creates a device record. #### Permitted OAuth 2.0 scopes @@ -916,8 +916,8 @@ Content-Type: application/json #### Error responses -* Passing an invalid `id` returns a `404 Not Found` status code with error code `E0000007`. -* Passing an `id` that is not in the `ACTIVE` or `SUSPENDED` status returns a `400 Bad Request` status code with the error code `E0000001`. +* Passing an invalid `id` returns a `404 Not Found` status code with the error code `E0000007`. +* Passing an `id` that isn’t in the `ACTIVE` or `SUSPENDED` status returns a `400 Bad Request` status code with the error code `E0000001`. ### Suspend Device @@ -986,8 +986,8 @@ Content-Type: application/json ###### Error response -* Passing an invalid `id` returns a `404 Not Found` status code with error code `E0000007`. -* Passing an `id` that is not in the `ACTIVE` status returns a `400 Bad Request` status code with error code `E0000001`. +* Passing an invalid `id` returns a `404 Not Found` status code with the error code `E0000007`. +* Passing an `id` that isn’t in the `ACTIVE` status returns a `400 Bad Request` status code with the error code `E0000001`. ### Unsuspend Device @@ -1049,8 +1049,8 @@ Content-Type: application/json ###### Error response -* Passing an invalid `id` returns a `404 Not Found` status code with error code `E0000007`. -* Passing an `id` that is not in the `SUSPENDED` status returns a `400 Bad Request` status code with error code `E0000001`. +* Passing an invalid `id` returns a `404 Not Found` status code with the error code `E0000007`. +* Passing an `id` that isn’t in the `SUSPENDED` status returns a `400 Bad Request` status code with the error code `E0000001`. ## Devices API objects @@ -1148,9 +1148,10 @@ The following diagram shows the state object for a Device: > **Note:** -> 1. Okta Verify enrollment results in a device being created in device inventory. The newly-created device has an `ACTIVE` status. -> 2. Device deactivation renders associated assets—such as device factors and management certificates—unusable. The Device re-enrollment/add account flow via Okta Verify allows end users to setup new factors (sign-in methods) on the device. -> 3. Deletion of the device after deactivation also deletes the device record from Okta. Re-enrollment of Okta Verify creates a new device record. +> +> * Okta Verify enrollment results in a device being created in the device inventory. The newly created device has an `ACTIVE` status. +> * Device deactivation renders associated assets—such as device factors and management certificates—unusable. The Device re-enrollment/add account flow through Okta Verify allows end users to set up new factors (sign-in methods) on the device. +> * Deletion of the device after deactivation also deletes the device record from Okta. Re-enrollment of Okta Verify creates a device record. ### Device profile object @@ -1158,19 +1159,19 @@ The following diagram shows the state object for a Device: | Property | Type | Description | | :----------------- | :--------- | :---------------------------------------------------------------------------------------------| -| `displayName` | String | Display name of the device. (1-255 characters) | -| `platform` | String | OS platform of the device. Possible values: `MACOS`, `WINDOWS`, `ANDROID`, `IOS` | -| `registered` | Boolean | Indicates if the device is registered at Okta. | -| `imei` | String | (Optional) International Mobile Equipment Identity of the device. (15-17 numeric characters) | -| `manufacturer` | String | (Optional) Name of the manufacturer of the device. (0-127 characters) | -| `meid` | String | (Optional) Mobile equipment identifier of the device. (14 characters) | -| `model` | String | (Optional) Model of the device. (127 characters) | -| `osVersion` | String | (Optional) Version of the device OS. (127 characters) | -| `serialNumber` | String | (Optional) Serial number of the device. (127 characters) | -| `sid` | String | (Optional) Windows Security identifier of the device. (256 characters) | -| `udid` | String | (Optional) macOS Unique Device identifier of the device. (47 characters) | -| `tpmPublicKeyHash` | String | (Optional) Windows Trsted Platform Module hash value. | -| `secureHardwarePresent` | Boolean | (Optional) Indicates if the device constains a secure hardware functionality. | +| `displayName` | String | The display name of the device (from 1 through 255 characters) | +| `platform` | String | OS platform of the device. Possible values: `MACOS`, `WINDOWS`, `ANDROID`, `IOS`. | +| `registered` | Boolean | Indicates if the device is registered at Okta | +| `imei` | String | (Optional) International Mobile Equipment Identity of the device (from 15 through 17 numeric characters) | +| `manufacturer` | String | (Optional) Name of the manufacturer of the device (from 0 through 127 characters) | +| `meid` | String | (Optional) Mobile equipment identifier of the device (14 characters) | +| `model` | String | (Optional) Model of the device (127 characters) | +| `osVersion` | String | (Optional) Version of the device OS (127 characters) | +| `serialNumber` | String | (Optional) Serial number of the device (127 characters) | +| `sid` | String | (Optional) Windows Security identifier of the device (256 characters) | +| `udid` | String | (Optional) macOS Unique Device identifier (47 characters) | +| `tpmPublicKeyHash` | String | (Optional) Windows Trusted Platform Module hash value | +| `secureHardwarePresent` | Boolean | (Optional) Indicates if the device contains a secure hardware functionality | #### Device profile example @@ -1196,7 +1197,7 @@ The following diagram shows the state object for a Device: #### Device object link attributes -For a Device result, the `_links` contains a full set of operations available for that device. `hints` provides information on allowed HTTP verbs for the `href`. +For a Device result, the `_links` parameter contains a full set of operations available for that device. The `hints` parameter provides information on allowed HTTP verbs for the `href`. Here are some links that may be available on a Device, as determined by its status: From e431bc3e7dd54f6060c303a5b139414403009772 Mon Sep 17 00:00:00 2001 From: brentschaus-okta <89146940+brentschaus-okta@users.noreply.github.com> Date: Wed, 26 Apr 2023 12:05:46 -0400 Subject: [PATCH 5/5] Update packages/@okta/vuepress-site/docs/reference/api/devices/index.md Co-authored-by: Brian Duffield - Okta <70648001+brianduffield-okta@users.noreply.github.com> --- .../@okta/vuepress-site/docs/reference/api/devices/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md index 9f9e0adbbba..d339a55251d 100644 --- a/packages/@okta/vuepress-site/docs/reference/api/devices/index.md +++ b/packages/@okta/vuepress-site/docs/reference/api/devices/index.md @@ -194,7 +194,7 @@ This operation: * Supports pagination (to a maximum of 200 results). * Requires [URL encoding](http://en.wikipedia.org/wiki/Percent-encoding). For example, `search=profile.displayName eq "Bob"` is encoded as `search=profile.displayName%20eq%20%22Bob%22`. -Searches include all Device profile properties, and the Device `id`, `status` and `lastUpdated` properties. +Searches include all Device profile properties, and the Device `id`, `status`, and `lastUpdated` properties. | Search term example | Description | | :---------------------------------------------- | :----------------------------------------------- |