Why isn't the `read_users` access scope documented as "custom app" only?

Hey y’all,

I’m hitting a wall here and just curious if anyone else has experience with the StaffMember object. In our Plus-only app (Onboard B2B) we give merchants the ability to assign sales staff to companies during the Company approval process - but the staff user has to have access our app first in order for us to be able to access them (because we don’t have access to read_users). This isn’t an ideal merchant experience because some of our shops don’t want to give their sales staff access to apps.

According to the docs here, we have to reach out to Support to enable access to this scope.

Requires read_users access scope. Also: The app must be a finance embedded app or installed on a Shopify Plus or Advanced store. Contact Shopify Support to enable this scope for your app.

When reaching out to support, they’re saying that this read_users is restricted to Plus stores using Custom apps. This is not documented anywhere in the docs and it’s really odd that it would be “restricted” to custom apps.

Hi @Jivan! You’re right that this should be documented more clearly. The restriction is mentioned in the REST Admin API User resource docs:

“The User resource is available for private apps and custom apps installed on Shopify Plus stores.”

But the GraphQL StaffMember docs and the main access scopes page don’t mention this - they just say “contact support to enable.” I’ve flagged this with the docs team internally to get this aligned. Thanks for pointing this out!

My understanding of the underlying reason is that read_users exposes staff member data (emails, permissions, etc.), which Shopify restricts to apps that have a direct trust relationship with the merchant - i.e., custom apps they’ve explicitly created and installed themselves. Public apps, even Plus-only ones, don’t have that same trust model.

Hey @Donal-Shopify, I appreciate the clarification here. The reasoning behind does make sense, although with customer PII we at least get a chance to request that in Partners (which one could argue is more sensitive than merchant staff data).

At the very least getting the email for a StaffMember would be great, but there’s no way to request this.

Also, on staffMembers docs here there’s no notice about needing access scopes until I go to nodes > [staffMember!] and actually click through to staffMember.

When querying in GraphiQL, staffMembers also gives me access denied.