GET /api/v1/users

Specifies the media type of the resource. Optional okta-response value can be included for performance optimization.

Complex DelAuth configurations may degrade performance when fetching specific parts of the response, and passing this parameter can omit these parts, bypassing the bottleneck.

Enum values for okta-response:

• omitCredentials: Omits the credentials subobject from the response.
• omitCredentialsLinks: Omits the following HAL links from the response: Update password, Change recovery question, Start forgot password flow, Reset password, Reset factors, Unlock.
• omitTransitioningToStatus: Omits the transitioningToStatus field from the response.

Specifies sort order: asc or desc (for search queries only). This parameter is ignored if sortBy isn't present.

Default value: "asc"

Specifies the number of results returned. Defaults to 10 if q is provided.

You can use limit with after to define the cursor location in the data set and manage the user records per page.

Default value: 200

Filters users with a supported expression for a subset of properties.

Note: Returned users include those with the DEPROVISIONED status.

This requires URL encoding. For example, filter=lastUpdated gt "2013-06-01T00:00:00.000Z" is encoded as filter=lastUpdated%20gt%20%222013-06-01T00:00:00.000Z%22. Filtering is case-sensitive for property names and query values, while operators are case-insensitive.

Filtering supports the following limited number of properties: status, lastUpdated, id, profile.login, profile.email, profile.firstName, and profile.lastName.

Additionally, filtering supports only the equal eq operator from the standard Okta API filtering semantics, except in the case of the lastUpdated property. This property can also use the inequality operators (gt, ge, lt, and le). For logical operators, only the logical operators and and or are supported. The not operator isn't supported. See Filter and Operators.

Specifies the field to sort by (for search queries only). This can be any single property, for example sortBy=profile.lastName. Users with the same value for the sortBy property are ordered by id. Use with sortOrder to control the order of results.

Finds users who match the specified query. Use the q parameter for simple queries, such as a lookup of users by name when creating a people picker.

The value of q is matched against firstName, lastName, or email. This performs a startsWith match, but this is an implementation detail and can change without notice. You don't need to specify firstName, lastName, or email.

Notes:

• Using the q parameter in a request omits users that have a status of DEPROVISIONED. To return all users, use a filter or search query instead.
• This doesn't support pagination, but you can use limit.
• This isn't designed for large data sets. For optimal performance, use the search parameter instead.

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination and Link header.

Searches for users with a supported filtering expression for most properties. Okta recommends this query parameter because it provides the largest range of search options and optimal performance.

Note: Using an overly complex or long search query can result in an error.

This operation supports pagination. Use an ID lookup for records that you update to ensure your results contain the latest data. Returned users include those with the DEPROVISIONED status.

Property names in the search parameter are case sensitive, whereas operators (eq, sw, and so on) and string values are case insensitive. Unlike with user logins, diacritical marks are significant in search string values: a search for isaac.brock finds Isaac.Brock, but doesn't find a property whose value is isáàc.bröck.

This operation requires URL encoding. See Special characters.

This operation searches many properties:

• Any user profile attribute, including custom-defined attributes
• The top-level properties: id, status, created, activated, statusChanged, and lastUpdated
• The user type accessed as type.id
• Properties that have array values

Note: The ability to search by user classification is available as an Early Access feature. The classification.type property cannot be used in conjunction with other search terms. You can search using classification.type eq "LITE" or classification.type eq "STANDARD".

You can also use sortBy and sortOrder parameters. The ne (not equal) operator isn't supported, but you can obtain the same result by using lt ... or ... gt. For example, to see all users except those that have a status of STAGED, use (status lt "STAGED" or status gt "STAGED").

You can search properties that are arrays. If any element matches the search term, the entire array (object) is returned. Okta follows the SCIM Protocol Specification for searching arrays. You can search multiple arrays, multiple values in an array, as well as using the standard logical and filtering operators. See Filter.

Searches for users can be filtered by the following operators: sw, eq, and co. You can only use co with these select user profile attributes: profile.firstName, profile.lastName, profile.email, and profile.login. See Operators.

A parameter to include metadata in the _embedded property. Supported value: classification.

Specifies a select set of user properties to query. Any other properties will be filtered out of the returned users. This is often called field projections in APIs, which can reduce payload size, improve performance, and limit unneccessary data exposure.

Requested fields should be comma-separated. Comma-separate the fields and place sub-fields in the profile object inside a profile:() directive, for example profile:(firstName, city). The id field is always included, regardless of whether it's specified in the fields parameter.