/devices is missing info on getting users, etc

[gabrielsroka]

https://developer.okta.com/docs/reference/api/devices is missing info on getting users (and perhaps other related collections)

to get a device's users:
GET /api/v1/devices/${deviceId}/users

this would be analogous to getting a group's users:
GET /api/v1/groups/${groupId}/users
which is documented here: https://developer.okta.com/docs/reference/api/groups/#list-group-members

[brianduffield-okta]

Thanks, Gabriel. Will review and get back to you on this one, too.

[gabrielsroka]

also missing info on

/api/v1/devices?search=managementStatus eq "MAN"&expand=user
/api/v1/devices?search=managementStatus eq "UNMAN"&expand=user

etc

EDIT: added &expand=user to clarify

[brianduffield-okta]

Logged internal ticket to address: https://oktainc.atlassian.net/browse/OKTA-567622

[gabrielsroka]

Any news on this?

[brianduffield-okta]

Assigned it to another writer. Let me check.

[gabrielsroka]

Any news?

[brianduffield-okta]

Hi Gabriel,

Unfortunately, just in the backlog, I think. The monthly release is taking precedence at the moment; hopefully, after that.

Brian

[brentschaus-okta]

Hi @gabrielsroka ,

I've chatted with the Devices team (some of whom remember you from your Okta days).

They wonder if the following operation handles your use cases: https://developer.okta.com/docs/reference/api/devices/#usage-example-expand-user

If not, please let us know what's missing. We do realize that we should doc the following:

search=managementStatus eg MAN

I look forward to hearing from you,

Brent

[gabrielsroka]

Your link expands users for all devices. My example is for one specific device. I think both of useful.

What's missing

I don't know. I'm reverse engineering the API by using the UI. It seems better to ask the engineers what's in the API so we can document it.

[brentschaus-okta]

Hi Gabriel,

The new operation is live on the "old" docs site: https://developer.okta.com/docs/reference/api/devices/#list-all-users-for-a-device

And will be live on the new redocly site in a few days (it'll appear at the bottom of the list of operations in the left nav): https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/

I know we still need to capture the details of the managementStatus parameter. I'll do that soon in another PR.

[gabrielsroka]

it doesn't seem to paginate, nor accept the limit or after parameters

[brentschaus-okta]

it doesn't seem to paginate, nor accept the limit or after parameters

Okay... following up. Sorry for the delay.

[gabrielsroka]

hi again,

this came up again today. you said on May 4 that it was on the old site, now the old site is gone, and it's not on the new site. EDIT: nm, i was confused.

i opened this issue in Dec. do u have an ETC?

[brentschaus-okta]

Hi @gabrielsroka , are we now able to close this issue? Thank you again for your patience.

[gabrielsroka]

Waiting on this

#3789 (comment)

[vanngo-okta]

Hi @gabrielsroka , can you please review this List Devices reference?
We recently updated the expand query parameter with user info and added pagination content. Please let us know if this addresses your issues. Thanks!

[gabrielsroka]

1. the doc still doesn't mention managementStatus , see /devices is missing info on getting users, etc #3789 (comment)
2. ?expand=userSummary doesn't work (but ?expand=user does)

[gabrielsroka]

also need devices for a given user /api/v1/users/${userId}/devices

[vanngo-okta]

Sorry @gabrielsroka , I got ahead of myself, the expand=userSummary option is currently being deployed on Preview. If you have a Production org, you won't see the feature until next week.

For your other questions:

1. The following requests aren't supported:

/api/v1/devices?search=managementStatus eq "MAN"
/api/v1/devices?search=managementStatus eq "UNMAN"

managementStatus property is inside the _embedded.users array payload, so you can't do a search on that optional payload. You can do a search on a specific device ID, and set expand=user to pick up the managementStatus property in the expanded payload. (Also, managementStatus = MANAGED | NOT_MANAGED )

2. The GET /api/v1/devices/{deviceId}/users endpoint doesn't support the search query parameter.

[gabrielsroka]

i confirmed userSummary works in preview. thanks.

1. aren't supported

what do you mean "not supported"? i tried it. it works. it's how the UI does it, too. did u try it?

2. GET /api/v1/devices/{deviceId}/users

i'm not sure what you're referencing here.

[vanngo-okta]

i confirmed userSummary works in preview. thanks.

Note that managementStatus isn't returned for userSummary yet (it should be added as a payload soon)

1. aren't supported

what do you mean "not supported"? i tried it. it works. it's how the UI does it, too. did u try it?

When I try this request, I don't get anything meaningful. But going by the reference docs, managementStatus is not a first-level property from the Devices payload, so this request isn't officially supported. If you have questions about API behaviour, please contact Okta support.
If you think it's a documentation issue, what do you think needs updating? I can create a doc request and follow up on the doc-gap.

2. GET /api/v1/devices/{deviceId}/users

i'm not sure what you're referencing here.

I thought one of your questions was about using search on GET /api/v1/devices/{deviceId}/users. Apologies if this is not the case. I'm getting confused with the long trail.

also need devices for a given user /api/v1/users/${userId}/devices

I can't find documentation on this endpoint (it's probably not supported). Nevertheless, I'll open a doc query into this endpoint to confirm. Thanks for your patience while we migrate to the OpenAPI spec.

[gabrielsroka]

this is what the UI does [1] [2]

Okta customers need this functionality via the API, too (not just the UI). since it's undocumented but easily discoverable, i'm asking for it to be documented since it's useful and necessary.

contact Okta support

I'm not a customer. i'm trying to help customers who are asking for this stuff.

/api/v1/users/${userId}/devices

again, the UI does this. customers need it. it's a public (but undocumented) api. i'm asking for it to be documented.

[1] managed MAN

---

[2] unmanaged UNMAN

[gabrielsroka]

note what was said in the above 2 comments by @brentschaus-okta

We do realize that we should doc the following:
search=managementStatus eg MAN

#3789 (comment)

we still need to capture the details of the managementStatus parameter. I'll do that soon

#3789 (comment)

[jefftaylor-okta]

@gabrielsroka Thanks for calling this out and for your patience working through the issue here! I think our best approach from this point is to both work with CSMs and support to engage with internal teams and also log some Okta Ideas to reflect the behavior you need and get support from the larger community. This will provide better justification for this request. Thanks again!

[gabrielsroka]

any update on this @brentschaus-okta , et al? it's been 18 months.

yet another Okta customer asked for this.

[brianduffield-okta]

Hi Gabriel, this was left in the Engineering and PM's court as last I recall. Let me re-engage with the team.

[camscale]

Nevertheless, I'll open a doc query into this endpoint to confirm.

@vanngo-okta Any follow-up on this? I would like to use the /v1/users/{userID}/devices API rather than returning all devices via the /v1/devices (with userSummary embedded objects) and manually filtering by the user I need.

[brianduffield-okta]

Hi @camscale, thanks for the note. Still working with our engineering/PM team on this. I've pinged the current dev manager and hope to get a resolution for you shortly.

[onekmilesbehind]

@brianduffield-okta

Brian I know you were going to check on this, but I wanted to echo what @camscale and @gabrielsroka are saying.

I've got ~3500 users I need to grab managed device status info on based on event triggers in workflows, so using the /api/v1/users/{userID}/devices endpoint is MUCH preferred over dumping everything from /api/v1/devices?expand=user.

Since this isn't documented anywhere, but the endpoint is clearly valid, can we expect this to function in the future? I'm a bit leery to employ this in a workflow without knowing it's not going to be abandoned next week.

Thanks ahead of time for any info you're able to glean from the other teams at Okta.

[brianduffield-okta]

@onekmilesbehind Thanks for the comment and information. This should help. Many apologies for the delay on this.

[gabrielsroka]

my $0.02. the admin UI uses it (it needs to), so i think it'll continue to work.

in 9 years of working with Okta, i've seen very few APIs (private or public) break. a few have changed in a small, but fixable way.