> For the complete documentation index, see [llms.txt](https://docs.defguard.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.defguard.net/2.1/for-developers/rest-api/core/user/list-users.md).

# List users

```json
{"openapi":"3.1.0","info":{"title":"defguard Core API","version":"2.1.0"},"tags":[{"name":"user","description":"User accounts, their MFA methods, enrollment and bulk operations."}],"security":[{"cookie":[]},{"api_token":[]}],"components":{"securitySchemes":{"cookie":{"type":"apiKey","in":"cookie","name":"defguard_session"},"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SortKey":{"type":"string","enum":["username","name","email"]},"SortOrder":{"type":"string","enum":["asc","desc"]},"PaginatedApiResponse_UserInfo":{"type":"object","description":"Envelope returned by paginated endpoints.","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","username","last_name","first_name","name","email","mfa_enabled","totp_enabled","email_mfa_enabled","groups","mfa_method","authorized_apps","is_active","enrolled","is_admin","ldap_pass_requires_change","password_management_disabled","devices","has_non_mfa_location_access","has_non_posture_location_access"],"properties":{"authorized_apps":{"type":"array","items":{"$ref":"#/components/schemas/OAuth2AuthorizedAppInfo"}},"devices":{"type":"array","items":{"$ref":"#/components/schemas/UserDevice"}},"email":{"type":"string"},"email_mfa_enabled":{"type":"boolean"},"enrolled":{"type":"boolean"},"first_name":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"has_non_mfa_location_access":{"type":"boolean"},"has_non_posture_location_access":{"type":"boolean"},"id":{"$ref":"#/components/schemas/i64"},"is_active":{"type":"boolean"},"is_admin":{"type":"boolean"},"last_name":{"type":"string"},"ldap_pass_requires_change":{"type":"boolean"},"mfa_enabled":{"type":"boolean"},"mfa_method":{"$ref":"#/components/schemas/MFAMethod"},"name":{"type":"string"},"password_management_disabled":{"type":"boolean"},"phone":{"type":["string","null"]},"totp_enabled":{"type":"boolean"},"username":{"type":"string"}}},"description":"Items of the requested page."},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"OAuth2AuthorizedAppInfo":{"type":"object","required":["oauth2client_id","oauth2client_name"],"properties":{"oauth2client_id":{"$ref":"#/components/schemas/i64"},"oauth2client_name":{"type":"string"}}},"i64":{"type":"integer","format":"int64"},"UserDevice":{"allOf":[{"$ref":"#/components/schemas/Device_i64"},{"type":"object","required":["networks"],"properties":{"networks":{"type":"array","items":{"$ref":"#/components/schemas/UserDeviceNetworkInfo"}}}}]},"Device_i64":{"type":"object","required":["id","name","wireguard_pubkey","user_id","created","device_type","configured"],"properties":{"configured":{"type":"boolean","description":"Whether the device is ready to use. Unconfigured devices are not sent to the gateway.\nSuch a device is already added to all its networks, but is still missing something,\nfor example its public key."},"created":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"device_type":{"$ref":"#/components/schemas/DeviceType"},"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"user_id":{"$ref":"#/components/schemas/i64"},"wireguard_pubkey":{"type":"string"}}},"DeviceType":{"type":"string","enum":["user","network"]},"UserDeviceNetworkInfo":{"type":"object","required":["network_id","network_name","network_gateway_ip","device_wireguard_ips","is_active","location_mfa_mode"],"properties":{"device_wireguard_ips":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"last_connected_at":{"type":["string","null"],"format":"date-time"},"last_connected_ip":{"type":["string","null"]},"location_mfa_mode":{"$ref":"#/components/schemas/LocationMfaMode"},"network_gateway_ip":{"type":"string"},"network_id":{"$ref":"#/components/schemas/i64"},"network_name":{"type":"string"}}},"LocationMfaMode":{"type":"string","enum":["disabled","internal","external"]},"MFAMethod":{"type":"string","enum":["None","OneTimePassword","Webauthn","Email"]},"PaginationMeta":{"type":"object","description":"Pagination metadata included in the response.","required":["current_page","page_size","total_items","total_pages"],"properties":{"current_page":{"type":"integer","format":"int32","description":"Number of the returned page, starting from 1.","minimum":0},"next_page":{"type":["integer","null"],"format":"int32","description":"Number of the next page, or `null` on the last page.","minimum":0},"page_size":{"type":"integer","format":"int32","description":"Requested page size.","minimum":0},"total_items":{"type":"integer","format":"int32","description":"Total number of items matching the query.","minimum":0},"total_pages":{"type":"integer","format":"int32","description":"Total number of pages for the requested page size.","minimum":0}}},"ApiErrorResponse":{"type":"object","description":"Body returned with error responses.","required":["msg"],"properties":{"code":{"type":["string","null"],"description":"Machine-readable error code, returned for selected errors."},"msg":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/api/v1/user":{"get":{"tags":["user"],"summary":"List users","operationId":"list_users","parameters":[{"name":"page","in":"query","description":"Page number. Defaults to 1.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"per_page","in":"query","description":"Number of items per page, from 1 to 100. Defaults to 50.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"groups","in":"query","description":"Filter by group names. Returns users belonging to any of the given groups.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"no_group","in":"query","description":"Filter users with no group membership. Combined with `groups`, returns users in the given groups and users with no group.","required":false,"schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Free-text search across username, first name, last name, and email.","required":false,"schema":{"type":"string"}},{"name":"sort_by","in":"query","description":"Sort key: `name`, `username`, or `email`. Defaults to `name`.","required":false,"schema":{"$ref":"#/components/schemas/SortKey"}},{"name":"sort_order","in":"query","description":"Sort direction: `asc` or `desc`. Defaults to `asc`.","required":false,"schema":{"$ref":"#/components/schemas/SortOrder"}}],"responses":{"200":{"description":"Paginated list of users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedApiResponse_UserInfo"}}}},"401":{"description":"Session is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Requires admin privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Unable to list users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```