List users in the application's user scope

List users in the application's user scope. GET /api/openapi/v1/users, scope admin.v1.user-directory.read.

Scope: admin.v1.user-directory.read
Permission: Read users and departments (user-directory)
Permission type: Read
Endpoint: GET/api/openapi/v1/users

Authentication and request headers

Call with an application API key. This endpoint checks only the scope above; read, manage and execute permissions do not imply one another.

Name	Location	Type	Required	Description	Example
Authorization	header	string	Yes	Application API key, passed as a Bearer token.	Bearer qwk_***
X-Request-Id	header	string	No	Optional request tracing identifier; generated by the server if omitted.	req-20260831-001

Request parameters

Name	Location	Type	Required	Description	Example
third_party_user_ids	query	array ｜ null	No	Repeated third-party user IDs (at most 100; each 1-255 characters after trimming). Case-sensitive exact match, intersected with other filters and application user scope. Empty values are rejected. Omit to leave this filter unset.	["<string>"]
keyword	query	string	No	Search keyword	"<string>"
department_id	query	string · uuid	No	Department (department ID)	"<uuid>"
status	query	string	No	User status	"pending"
seat_status	query	string	No	Seat assignment	"assigned"
page	query	integer · int64	No	Page number	1
page_size	query	integer · int64	No	Page size	20

Request example

cURL

Responses

200 OK

Name	Type	Required	Description	Example
items	array ｜ null	Yes	User list.	[{"account":"<string>","department_ids":["<string>"],"email":"<string>","job_number":"<string>","name":"<string>","phone":"<string>","qid":"<uuid>","seat_status":"assigned","source":"manual","status":"pending","updated_at":"2026-08-27T10:00:00Z","third_party_user_id":"external-001","departments":[{"id":"22222222-2222-4222-8222-222222222222","name":"Engineering","path":"Company/Engineering","external_id":"external-dept","is_primary":true}],"credential":{"password_state":"active","must_change_password":false,"credential_version":2},"created_at":"2026-09-19T01:00:00Z","last_active_at":"2026-09-23T01:00:00Z"}]
page	integer · int64	Yes	Page number	0
page_size	integer · int64	Yes	Page size	0
total	integer · int64	Yes	Total count	0
items[].third_party_user_id	string	Yes	External user ID; an empty string when unset.	"external-001"
items[].departments	array	Yes	Department details; an empty array when no departments are assigned.	[{"id":"22222222-2222-4222-8222-222222222222","name":"Engineering","path":"Company/Engineering","external_id":"external-dept","is_primary":true}]
items[].credential	object	Yes	Password lifecycle metadata; contains no password or hash.	{"password_state":"active","must_change_password":false,"credential_version":2}
items[].created_at	string · date-time	Yes	User creation time.	"2026-09-19T01:00:00Z"
items[].last_active_at	string · date-time	No	Latest IAM activity time; omitted when unavailable. This is not the latest business activity time.	"2026-09-23T01:00:00Z"
items[].departments[].id	string · uuid	Yes	Department ID.	-
items[].departments[].name	string	Yes	Department name.	-
items[].departments[].path	string	Yes	Department path.	-
items[].departments[].external_id	string	No	External department ID; omitted when unset.	-
items[].departments[].is_primary	boolean	Yes	Whether this is the primary department.	-
items[].credential.password_state	string	Yes	Password state: unset (not set), initial (initial password), or active (active password).	-
items[].credential.must_change_password	boolean	Yes	Whether a password change is required.	-
items[].credential.credential_version	integer	Yes	Credential version.	-
items[].credential.password_updated_at	string · date-time	No	Password update time; omitted when unavailable.	-
items[].credential.first_login_completed_at	string · date-time	No	First completed sign-in time; omitted before completion.	-

Response example

default Flat business error

Name	Type	Required	Description	Example
code	string	No	Stable business error code	"<string>"
detail	string	Yes	Human-readable error description	"<string>"
details	OpenapiErrorDetails	No	Error details	{"field":"<string>","reason":"<string>","suggestion":"<string>"}
details.field	string	No	Request field that failed validation	"<string>"
details.reason	string	No	Stable validation failure reason	"<string>"
details.suggestion	string	No	Suggested normalized value	"<string>"
error	string	Yes	Stable HTTP error type	"<string>"

Response example

On this page

Authentication and request headers
Request parameters
Request example
Responses

List users in the application's user scope - QwenWork