users

Creates, updates, deletes, gets or lists a users resource.

Overview

Name	users
Type	Resource
Id	okta.users.users

Fields

The following fields are returned by SELECT queries:

list_users

Name	Datatype	Description
id	string	The unique key for the user
_embedded	object	Embedded resources related to the user using the JSON Hypertext Application Language specification
_links	object	Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
activated	string (date-time)	The timestamp when the user status transitioned to ACTIVE
created	string (date-time)	The timestamp when the user was created
credentials	object	Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the org.
lastLogin	string (date-time)	The timestamp of the last login
lastUpdated	string (date-time)	The timestamp when the user was last updated
passwordChanged	string (date-time)	The timestamp when the user's password was last updated
profile	object	Specifies the default and custom profile properties for a user. The default user profile is based on the System for Cross-domain Identity Management: Core Schema. The only permitted customizations of the default profile are to update permissions, change whether the firstName and lastName properties are nullable, and specify a pattern for login. You can use the Profile Editor in the Admin Console or the Schemas API to make schema modifications. You can extend user profiles with custom properties. You must first add the custom property to the user profile schema before you reference it. You can use the Profile Editor in the Admin Console or the Schemas API to manage schema extensions. Custom attributes can contain HTML tags. It's the client's responsibility to escape or encode this data before displaying it. Use best-practices to prevent cross-site scripting.
realmId	string	The ID of the realm in which the user is residing. See Realms. (example: guo1bfiNtSnZYILxO0g4)
status	string	The current status of the user. The status of a user changes in response to explicit events, such as admin-driven lifecycle changes, user login, or self-service password recovery. Okta doesn't asynchronously sweep through users and update their password expiry state, for example. Instead, Okta evaluates password policy at login time, notices the password has expired, and moves the user to the expired state. When running reports, remember that the data is valid as of the last login or lifecycle event for that user.
statusChanged	string (date-time)	The timestamp when the status of the user last changed
transitioningToStatus	string	The target status of an in-progress asynchronous status transition. This property is only returned if the user's state is transitioning.
type	object	The user type that determines the schema for the user's profile. The type property is a map that identifies the User Types. Currently it contains a single element, id. It can be specified when creating a new user, and ca be updated by an admin on a full replace of an existing user (but not a partial update).

get_user

Name	Datatype	Description
id	string	The unique key for the user
_embedded	object	The embedded resources related to the object if the expand query parameter is specified
_links	object	Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
activated	string (date-time)	The timestamp when the user status transitioned to ACTIVE
created	string (date-time)	The timestamp when the user was created
credentials	object	Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the org.
lastLogin	string (date-time)	The timestamp of the last login
lastUpdated	string (date-time)	The timestamp when the user was last updated
passwordChanged	string (date-time)	The timestamp when the user's password was last updated
profile	object	Specifies the default and custom profile properties for a user. The default user profile is based on the System for Cross-domain Identity Management: Core Schema. The only permitted customizations of the default profile are to update permissions, change whether the firstName and lastName properties are nullable, and specify a pattern for login. You can use the Profile Editor in the Admin Console or the Schemas API to make schema modifications. You can extend user profiles with custom properties. You must first add the custom property to the user profile schema before you reference it. You can use the Profile Editor in the Admin Console or the Schemas API to manage schema extensions. Custom attributes can contain HTML tags. It's the client's responsibility to escape or encode this data before displaying it. Use best-practices to prevent cross-site scripting.
realmId	string	The ID of the realm in which the user is residing. See Realms. (example: guo1bfiNtSnZYILxO0g4)
status	string	The current status of the user. The status of a user changes in response to explicit events, such as admin-driven lifecycle changes, user login, or self-service password recovery. Okta doesn't asynchronously sweep through users and update their password expiry state, for example. Instead, Okta evaluates password policy at login time, notices the password has expired, and moves the user to the expired state. When running reports, remember that the data is valid as of the last login or lifecycle event for that user.
statusChanged	string (date-time)	The timestamp when the status of the user last changed
transitioningToStatus	string	The target status of an in-progress asynchronous status transition. This property is only returned if the user's state is transitioning.
type	object	The user type that determines the schema for the user's profile. The type property is a map that identifies the User Types. Currently it contains a single element, id. It can be specified when creating a new user, and ca be updated by an admin on a full replace of an existing user (but not a partial update).

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_users	select	subdomain	Content-Type, search, filter, q, after, limit, sortBy, sortOrder, expand	Lists users in your org, with pagination in most cases. A subset of users can be returned that match a supported filter expression or search criteria. Different results are returned depending on specified queries in the request. > Note: This operation omits users that have a status of DEPROVISIONED in the response. To return all users, use a filter or search query instead.
get_user	select	subdomain	Content-Type, expand	Retrieves a user from your Okta org. You can substitute me for the id to fetch the current user linked to an API token or session cookie. * The request returns the user linked to the API token that is specified in the Authorization header, not the user linked to the active session. Details of the admin user who granted the API token is returned. * When the end user has an active Okta session, it is typically a CORS request from the browser. Therefore, it's possible to retrieve the current user without the Authorization header. When fetching a user by login or login shortname, URL encode the request parameter to ensure that special characters are escaped properly. Logins with a / character can only be fetched by id due to URL issues with escaping the / character. If you don't know a user's ID, you can use the List all users endpoint to find it. > Note: Some browsers block third-party cookies by default, which disrupts Okta functionality in certain flows. See Mitigate the impact of third-party cookie deprecation.
create_user	insert	subdomain, data__profile	activate, provider, nextLogin	Creates a new user in your Okta org with or without credentials. > Legal Disclaimer > > After a user is added to the Okta directory, they receive an activation email. As part of signing up for this service, > you agreed not to use Okta's service/product to spam and/or send unsolicited messages. > Please refrain from adding unrelated accounts to the directory as Okta is not responsible for, and disclaims any and all > liability associated with, the activation email's content. You, and you alone, bear responsibility for the emails sent to any recipients. All responses return the created user. Activation of a user is an asynchronous operation. The system performs group reconciliation during activation and assigns the user to all apps via direct or indirect relationships (group memberships). * The user's transitioningToStatus property is ACTIVE during activation to indicate that the user hasn't completed the asynchronous operation. * The user's status is ACTIVE when the activation process is complete. The user is emailed a one-time activation token if activated without a password. > Note: If the user is assigned to an app that is configured for provisioning, the activation process triggers downstream provisioning to the app. It is possible for a user to sign in before these apps have been successfully provisioned for the user. > Important: Do not generate or send a one-time activation token when activating users with an assigned password. Users should sign in with their assigned password. For more information about the various scenarios of creating a user listed in the examples, see the User creation scenarios section.
update_user	update	subdomain	strict, If-Match	Updates a user's profile or credentials with partial update semantics. > Important: Use the POST method for partial updates. Unspecified properties are set to null with PUT. profile and credentials can be updated independently or together with a single request. > Note: Currently, the user type of a user can only be changed via a full replacement PUT operation. If the request parameters of a partial update include the type element from the user object, the value must match the existing type of the user. Only admins are permitted to change the user type of a user; end users are not allowed to change their own user type. > Note: To update a current user's profile with partial semantics, the /api/v1/users/me endpoint can be invoked. > > A user can only update profile properties for which the user has write access. Within the profile, if the user tries to update the primary or the secondary email IDs, verification emails are sent to those email IDs, and the fields are updated only upon verification. If you are using this endpoint to set a password, it sets a password without validating existing user credentials. This is an administrative operation. For operations that validate credentials, refer to the Reset password, Start forgot password flow, and Update password endpoints.
replace_user	replace	subdomain	strict, If-Match	Replaces a user's profile, credentials, or both using strict-update semantics. All profile properties must be specified when updating a user's profile with a PUT method. Any property not specified in the request is deleted. > Important: Don't use a PUT method for partial updates.
delete_user	delete	subdomain	sendEmail, Prefer	Deletes a user permanently. This operation can only be performed on users that have a DEPROVISIONED status. > Warning: This action can't be recovered! This operation on a user that hasn't been deactivated causes that user to be deactivated. A second delete operation is required to delete the user. > Note: You can also perform user deletion asynchronously. To invoke asynchronous user deletion, pass an HTTP header Prefer: respond-async with the request. This header is also supported by user deactivation, which is performed if the delete endpoint is invoked on a user that hasn't been deactivated.
end_user_sessions	exec	subdomain		Ends Okta sessions for the currently signed in user. By default, the current session remains active. Use this method in a browser-based app. > Note: This operation requires a session cookie for the user. The API token isn't allowed for this operation.
activate_user	exec	subdomain	sendEmail	Activates a user. Perform this operation only on users with a STAGED or DEPROVISIONED status. Activation of a user is an asynchronous operation. * The user has the transitioningToStatus property with an ACTIVE value during activation. This indicates that the user hasn't completed the asynchronous operation. * The user has an ACTIVE status when the activation process completes. Users who don't have a password must complete the welcome flow by visiting the activation link to complete the transition to ACTIVE status. > Note: If you want to send a branded user activation email, change the subdomain of your request to the custom domain that's associated with the brand. > For example, change subdomain.okta.com to custom.domain.one. See Multibrand and custom domains. > Note: If you have optional password enabled, visiting the activation link is optional for users who aren't required to enroll a password. > See Create user with optional password. > Legal disclaimer > After a user is added to the Okta directory, they receive an activation email. As part of signing up for this service, > you agreed not to use Okta's service/product to spam and/or send unsolicited messages. > Please refrain from adding unrelated accounts to the directory as Okta is not responsible for, and disclaims any and all > liability associated with, the activation email's content. You, and you alone, bear responsibility for the emails sent to any recipients.
deactivate_user	exec	subdomain	sendEmail, Prefer	Deactivates a user. Perform this operation only on users that do not have a DEPROVISIONED status. * The user's transitioningToStatus property is DEPROVISIONED during deactivation to indicate that the user hasn't completed the asynchronous operation. * The user's status is DEPROVISIONED when the deactivation process is complete. > Important: Deactivating a user is a destructive operation. The user is deprovisioned from all assigned apps, which might destroy their data such as email or files. This action cannot be recovered! You can also perform user deactivation asynchronously. To invoke asynchronous user deactivation, pass an HTTP header Prefer: respond-async with the request.
expire_password	exec	subdomain		Expires the password. This operation transitions the user status to PASSWORD_EXPIRED so that the user must change their password the next time that they sign in. If you have integrated Okta with your on-premises Active Directory (AD), then setting a user's password as expired in Okta also expires the password in AD. When the user tries to sign in to Okta, delegated authentication finds the password-expired status in AD, and the user is presented with the password-expired page where they can change their password. > Note: The Okta account management policy doesn't support the /users/{id}/lifecycle/expire_password endpoint. See Configure an Okta account management policy.
expire_password_with_temp_password	exec	subdomain	revokeSessions	Expires the password and resets the user's password to a temporary password. This operation transitions the user status to PASSWORD_EXPIRED so that the user must change their password the next time that they sign in. The user's password is reset to a temporary password that's returned, and then the user's password is expired. If revokeSessions is included in the request with a value of true, the user's current outstanding sessions are revoked and require re-authentication. If you have integrated Okta with your on-premises Active Directory (AD), then setting a user's password as expired in Okta also expires the password in AD. When the user tries to sign in to Okta, delegated authentication finds the password-expired status in AD, and the user is presented with the password-expired page where they can change their password.
reactivate_user	exec	subdomain	sendEmail	Reactivates a user. Perform this operation only on users with a PROVISIONED or RECOVERY status. This operation restarts the activation workflow if for some reason the user activation wasn't completed when using the activationToken from Activate User. Users that don't have a password must complete the flow by completing the Reset password flow and MFA enrollment steps to transition the user to ACTIVE status. If sendEmail is false, returns an activation link for the user to set up their account. The activation token can be used to create a custom activation link.
reset_factors	exec	subdomain		Resets all factors for the specified user. All MFA factor enrollments return to the unenrolled state. The user's status remains ACTIVE. This link is present only if the user is currently enrolled in one or more MFA factors.
reset_password	exec	sendEmail, subdomain	revokeSessions	Resets a password. Generates a one-time token (OTT) that you can use to reset a user's password. You can automatically email the OTT link to the user or return the OTT to the API caller and distribute using a custom flow. This operation transitions the user to the RECOVERY status. The user is then not able to sign in or initiate a forgot password flow until they complete the reset flow. This operation provides an option to delete all the user's sessions. However, if the request is made in the context of a session owned by the specified user, that session isn't cleared. > Note: You can also use this API to convert a user with the Okta credential provider to use a federated provider. After this conversion, the user can't directly sign in with a password. > To convert a federated user back to an Okta user, use the default API call. If an email address is associated with multiple users, keep in mind the following to ensure a successful password recovery lookup: * Okta no longer includes deactivated users in the lookup. * The lookup searches sign-in IDs first, then primary email addresses, and then secondary email addresses. If sendEmail is false, returns a link for the user to reset their password.
suspend_user	exec	subdomain		Suspends a user. Perform this operation only on users with an ACTIVE status. The user has a SUSPENDED status when the process completes. Suspended users can't sign in to Okta. They can only be unsuspended or deactivated. Their group and app assignments are retained.
unlock_user	exec	subdomain		Unlocks a user with a LOCKED_OUT status or unlocks a user with an ACTIVE status that's blocked from unknown devices. Unlocked users have an ACTIVE status and can sign in with their current password. > Note: This operation works with Okta-sourced users. It doesn't support directory-sourced accounts such as Active Directory.
unsuspend_user	exec	subdomain		Unsuspends a user and returns them to the ACTIVE state. This operation can only be performed on users that have a SUSPENDED status.
change_password	exec	subdomain	strict	Updates a user's password by validating the user's current password. This operation provides an option to delete all the sessions of the specified user. However, if the request is made in the context of a session owned by the specified user, that session isn't cleared. You can only perform this operation on users in STAGED, ACTIVE, PASSWORD_EXPIRED, or RECOVERY status that have a valid password credential. The user transitions to ACTIVE status when successfully invoked in RECOVERY status. > Note: The Okta account management policy doesn't support the /users/{userId}/credentials/change_password endpoint. See Configure an Okta account management policy.
change_recovery_question	exec	subdomain		Updates a user's recovery question and answer credential by validating the user's current password. You can only perform this operation on users in STAGED, ACTIVE, or RECOVERY status that have a valid password credential.
forgot_password	exec	subdomain	sendEmail	Starts the forgot password flow. Generates a one-time token (OTT) that you can use to reset a user's password. The user must validate their security question's answer when visiting the reset link. Perform this operation only on users with an ACTIVE status and a valid recovery question credential. > Note: If you have migrated to Identity Engine, you can allow users to recover passwords with any enrolled MFA authenticator. See Self-service account recovery. If an email address is associated with multiple users, keep in mind the following to ensure a successful password recovery lookup: * Okta no longer includes deactivated users in the lookup. * The lookup searches sign-in IDs first, then primary email addresses, and then secondary email addresses. If sendEmail is false, returns a link for the user to reset their password. This operation doesn't affect the status of the user.
forgot_password_set_new_password	exec	subdomain	sendEmail	Resets the user's password to the specified password if the provided answer to the recovery question is correct. You must include the recovery question answer with the submission.
revoke_user_sessions	exec	subdomain	oauthTokens, forgetDevices	Revokes all active identity provider sessions of the user. This forces the user to authenticate on the next operation. Optionally revokes OpenID Connect and OAuth refresh and access tokens issued to the user. You can also clear the user's remembered factors for all devices using the forgetDevices parameter. See forgetDevices. > Note: This operation doesn't clear the sessions created for web or native apps.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
sendEmail	boolean
subdomain	string	The domain of your organization. This can be a provided subdomain of an official okta domain (okta.com, oktapreview.com, etc) or one of your configured custom domains. (default: my-org)
Content-Type	string	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.
If-Match	string	The ETag value of the user's expected current state. This becomes a conditional request used for concurrency control. See [Conditional Requests and Entity Tags]https://developer.okta.com/docs/api#conditional-requests-and-entity-tags. (example: W/"1234567890abcdef")
Prefer	string	Request asynchronous processing
activate	boolean	Executes an activation lifecycle operation when creating the user
after	string	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.
expand	string	An optional parameter to include metadata in the _embedded attribute. Valid values: blocks or <x-lifecycle class="ea"></x-lifecycle> classification.
filter	string	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.
forgetDevices	boolean	Clears the user's remembered factors for all devices. > Note: This parameter defaults to false in Classic Engine.
limit	integer (int32)	Specifies the number of results returned. Defaults to 10 if q is provided.
nextLogin	string	With activate=true, if nextLogin=changePassword, a user is created, activated, and the password is set to EXPIRED. The user must change it the next time they sign in.
oauthTokens	boolean	Revokes issued OpenID Connect and OAuth refresh and access tokens
provider	boolean	Indicates whether to create a user with a specified authentication provider
q	string	Finds users who match the specified query. This doesn't support pagination. > Note: For optimal performance, use the search parameter instead. 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. > Note: 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.
revokeSessions	boolean	Revokes all user sessions, except for the current session, if set to true
search	string	Searches for users with a supported filtering expression for most properties. Okta recommends using this parameter for optimal search 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. For example, search=profile.department eq "Engineering" is encoded as search=profile.department%20eq%20%22Engineering%22. If you use the special character " within a quoted string, it must also be escaped \ and encoded. For example, search=profile.lastName eq "bob"smith" is encoded as search=profile.lastName%20eq%20%22bob%5C%22smith%22. 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 > Note: <x-lifecycle class="ea"></x-lifecycle> 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.
sendEmail	boolean
sortBy	string	Specifies 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 will be ordered by id.
sortOrder	string	Specifies the sort order: asc or desc (for search queries only). Sorting is done in ASCII sort order (that is, by ASCII character value), but isn't case sensitive. sortOrder is ignored if sortBy isn't present.
strict	boolean	If true, validates against the password minimum age policy

SELECT examples

list_users

Lists users in your org, with pagination in most cases.

A subset of users can be returned that match a supported filter expression or search criteria. Different results are returned depending on specified queries in the request.

> Note: This operation omits users that have a status of DEPROVISIONED in the response. To return all users, use a filter or search query instead.

SELECT
id,
_embedded,
_links,
activated,
created,
credentials,
lastLogin,
lastUpdated,
passwordChanged,
profile,
realmId,
status,
statusChanged,
transitioningToStatus,
type
FROM okta.users.users
WHERE subdomain = '{{ subdomain }}' -- required
AND Content-Type = '{{ Content-Type }}'
AND search = '{{ search }}'
AND filter = '{{ filter }}'
AND q = '{{ q }}'
AND after = '{{ after }}'
AND limit = '{{ limit }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND expand = '{{ expand }}'
;

get_user

Retrieves a user from your Okta org.

You can substitute me for the id to fetch the current user linked to an API token or session cookie.
* The request returns the user linked to the API token that is specified in the Authorization header, not the user linked to the active session. Details of the admin user who granted the API token is returned.
* When the end user has an active Okta session, it is typically a CORS request from the browser. Therefore, it's possible to retrieve the current user without the Authorization header.

When fetching a user by login or login shortname, URL encode the request parameter to ensure that special characters are escaped properly. Logins with a / character can only be fetched by id due to URL issues with escaping the / character. If you don't know a user's ID, you can use the List all users endpoint to find it.

> Note: Some browsers block third-party cookies by default, which disrupts Okta functionality in certain flows. See Mitigate the impact of third-party cookie deprecation.

SELECT
id,
_embedded,
_links,
activated,
created,
credentials,
lastLogin,
lastUpdated,
passwordChanged,
profile,
realmId,
status,
statusChanged,
transitioningToStatus,
type
FROM okta.users.users
WHERE subdomain = '{{ subdomain }}' -- required
AND Content-Type = '{{ Content-Type }}'
AND expand = '{{ expand }}'
;

INSERT examples

create_user

Creates a new user in your Okta org with or without credentials.

> Legal Disclaimer
>
> After a user is added to the Okta directory, they receive an activation email. As part of signing up for this service,
> you agreed not to use Okta's service/product to spam and/or send unsolicited messages.
> Please refrain from adding unrelated accounts to the directory as Okta is not responsible for, and disclaims any and all
> liability associated with, the activation email's content. You, and you alone, bear responsibility for the emails sent to any recipients.

All responses return the created user. Activation of a user is an asynchronous operation. The system performs group reconciliation during activation and assigns the user to all apps via direct or indirect relationships (group memberships).
* The user's transitioningToStatus property is ACTIVE during activation to indicate that the user hasn't completed the asynchronous operation.
* The user's status is ACTIVE when the activation process is complete.

The user is emailed a one-time activation token if activated without a password.

> Note: If the user is assigned to an app that is configured for provisioning, the activation process triggers downstream provisioning to the app. It is possible for a user to sign in before these apps have been successfully provisioned for the user.

> Important: Do not generate or send a one-time activation token when activating users with an assigned password. Users should sign in with their assigned password.

For more information about the various scenarios of creating a user listed in the examples, see the User creation scenarios section.

INSERT INTO okta.users.users (
data__credentials,
data__groupIds,
data__profile,
data__realmId,
data__type,
subdomain,
activate,
provider,
nextLogin
)
SELECT 
'{{ credentials }}',
'{{ groupIds }}',
'{{ profile }}' /* required */,
'{{ realmId }}',
'{{ type }}',
'{{ subdomain }}',
'{{ activate }}',
'{{ provider }}',
'{{ nextLogin }}'
RETURNING
id,
_embedded,
_links,
activated,
created,
credentials,
lastLogin,
lastUpdated,
passwordChanged,
profile,
realmId,
status,
statusChanged,
transitioningToStatus,
type
;

Manifest

# Description fields are for documentation purposes
- name: users
  props:
    - name: subdomain
      value: string
      description: Required parameter for the users resource.
    - name: credentials
      value: object
      description: >
        Specifies primary authentication and recovery credentials for a user. Credential types and requirements vary depending on the provider and security policy of the org.
        
    - name: groupIds
      value: array
      description: >
        The list of group IDs of groups that the user is added to at the time of creation
        
    - name: profile
      value: object
      description: >
        Specifies the default and custom profile properties for a user.

The default user profile is based on the [System for Cross-domain Identity Management: Core Schema](https://datatracker.ietf.org/doc/html/rfc7643).

The only permitted customizations of the default profile are to update permissions, change whether the `firstName` and `lastName` properties are nullable, and specify a [pattern](https://developer.okta.com/docs/reference/api/schemas/#login-pattern-validation) for `login`. You can use the Profile Editor in the Admin Console or the [Schemas API](https://developer.okta.com/docs/apihttps://developer.okta.com/docs/api/openapi/okta-management/management/tag/UISchema/#tag/UISchema) to make schema modifications.

You can extend user profiles with custom properties. You must first add the custom property to the user profile schema before you reference it.
You can use the Profile Editor in the Admin Console or the [Schemas API](https://developer.okta.com/docs/apihttps://developer.okta.com/docs/api/openapi/okta-management/management/tag/UISchema/#tag/UISchema) to manage schema extensions.

Custom attributes can contain HTML tags. It's the client's responsibility to escape or encode this data before displaying it. Use [best-practices](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) to prevent cross-site scripting.
        
    - name: realmId
      value: string
      description: >
        The ID of the realm in which the user is residing. See [Realms](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Realm/).
        
    - name: type
      value: object
      description: >
        The ID of the user type. Add this value if you want to create a user with a non-default [User Type](https://developer.okta.com/docs/apihttps://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserType/).
The user type determines which [schema](https://developer.okta.com/docs/apihttps://developer.okta.com/docs/api/openapi/okta-management/management/tag/Schema/) applies to that user. After a user has been created, the user can
only be assigned a different user type by an administrator through a full replacement (`PUT`) operation.
        
    - name: activate
      value: boolean
      description: Executes an [activation lifecycle](https://developer.okta.com/docs/apihttps://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserLifecycle/#tag/UserLifecycle/operation/activateUser) operation when creating the user
    - name: provider
      value: boolean
      description: Indicates whether to create a user with a specified authentication provider
    - name: nextLogin
      value: string
      description: With `activate=true`, if `nextLogin=changePassword`, a user is created, activated, and the password is set to `EXPIRED`. The user must change it the next time they sign in.

UPDATE examples

update_user

Updates a user's profile or credentials with partial update semantics.

> Important: Use the POST method for partial updates. Unspecified properties are set to null with PUT.

profile and credentials can be updated independently or together with a single request.
> Note: Currently, the user type of a user can only be changed via a full replacement PUT operation. If the request parameters of a partial update include the type element from the user object,
the value must match the existing type of the user. Only admins are permitted to change the user type of a user; end users are not allowed to change their own user type.

> Note: To update a current user's profile with partial semantics, the /api/v1/users/me endpoint can be invoked.
>
> A user can only update profile properties for which the user has write access. Within the profile, if the user tries to update the primary or the secondary email IDs, verification emails are sent to those email IDs, and the fields are updated only upon verification.

If you are using this endpoint to set a password, it sets a password without validating existing user credentials. This is an administrative operation. For operations that validate credentials, refer to the Reset password, Start forgot password flow, and Update password endpoints.

UPDATE okta.users.users
SET 
data__credentials = '{{ credentials }}',
data__profile = '{{ profile }}',
data__realmId = '{{ realmId }}'
WHERE 
subdomain = '{{ subdomain }}' --required
AND strict = {{ strict}}
AND If-Match = '{{ If-Match}}'
RETURNING
id,
_embedded,
_links,
activated,
created,
credentials,
lastLogin,
lastUpdated,
passwordChanged,
profile,
realmId,
status,
statusChanged,
transitioningToStatus,
type
;

REPLACE examples

replace_user

Replaces a user's profile, credentials, or both using strict-update semantics.

All profile properties must be specified when updating a user's profile with a PUT method. Any property not specified in the request is deleted.
> Important: Don't use a PUT method for partial updates.

REPLACE okta.users.users
SET 
data__credentials = '{{ credentials }}',
data__profile = '{{ profile }}',
data__realmId = '{{ realmId }}'
WHERE 
subdomain = '{{ subdomain }}' --required
AND strict = {{ strict}}
AND If-Match = '{{ If-Match}}'
RETURNING
id,
_embedded,
_links,
activated,
created,
credentials,
lastLogin,
lastUpdated,
passwordChanged,
profile,
realmId,
status,
statusChanged,
transitioningToStatus,
type
;

DELETE examples

delete_user

Deletes a user permanently. This operation can only be performed on users that have a DEPROVISIONED status.

> Warning: This action can't be recovered!

This operation on a user that hasn't been deactivated causes that user to be deactivated. A second delete operation is required to delete the user.

> Note: You can also perform user deletion asynchronously. To invoke asynchronous user deletion, pass an HTTP header Prefer: respond-async with the request.

This header is also supported by user deactivation, which is performed if the delete endpoint is invoked on a user that hasn't been deactivated.

DELETE FROM okta.users.users
WHERE subdomain = '{{ subdomain }}' --required
AND sendEmail = '{{ sendEmail }}'
AND Prefer = '{{ Prefer }}'
;

Lifecycle Methods

end_user_sessions

Ends Okta sessions for the currently signed in user. By default, the current session remains active. Use this method in a browser-based app.
> Note: This operation requires a session cookie for the user. The API token isn't allowed for this operation.

EXEC okta.users.users.end_user_sessions 
@subdomain='{{ subdomain }}' --required 
@@json=
'{
"keepCurrent": {{ keepCurrent }}
}'
;

activate_user

Activates a user.

Perform this operation only on users with a STAGED or DEPROVISIONED status. Activation of a user is an asynchronous operation.
* The user has the transitioningToStatus property with an ACTIVE value during activation. This indicates that the user hasn't completed the asynchronous operation.
* The user has an ACTIVE status when the activation process completes.

Users who don't have a password must complete the welcome flow by visiting the activation link to complete the transition to ACTIVE status.

> Note: If you want to send a branded user activation email, change the subdomain of your request to the custom domain that's associated with the brand.
> For example, change subdomain.okta.com to custom.domain.one. See Multibrand and custom domains.

> Note: If you have optional password enabled, visiting the activation link is optional for users who aren't required to enroll a password.
> See Create user with optional password.

> Legal disclaimer
> After a user is added to the Okta directory, they receive an activation email. As part of signing up for this service,
> you agreed not to use Okta's service/product to spam and/or send unsolicited messages.
> Please refrain from adding unrelated accounts to the directory as Okta is not responsible for, and disclaims any and all
> liability associated with, the activation email's content. You, and you alone, bear responsibility for the emails sent to any recipients.

EXEC okta.users.users.activate_user 
@subdomain='{{ subdomain }}' --required, 
@sendEmail={{ sendEmail }}
;

deactivate_user

Deactivates a user.

Perform this operation only on users that do not have a DEPROVISIONED status.
* The user's transitioningToStatus property is DEPROVISIONED during deactivation to indicate that the user hasn't completed the asynchronous operation.
* The user's status is DEPROVISIONED when the deactivation process is complete.

> Important: Deactivating a user is a destructive operation. The user is deprovisioned from all assigned apps, which might destroy their data such as email or files.
This action cannot be recovered!

You can also perform user deactivation asynchronously. To invoke asynchronous user deactivation, pass an HTTP header Prefer: respond-async with the request.

EXEC okta.users.users.deactivate_user 
@subdomain='{{ subdomain }}' --required, 
@sendEmail={{ sendEmail }}, 
@Prefer='{{ Prefer }}'
;

expire_password

Expires the password. This operation transitions the user status to PASSWORD_EXPIRED so that the user must change their password the next time that they sign in.


If you have integrated Okta with your on-premises Active Directory (AD), then setting a user's password as expired in Okta also expires the password in AD.
When the user tries to sign in to Okta, delegated authentication finds the password-expired status in AD,
and the user is presented with the password-expired page where they can change their password.

> Note: The Okta account management policy doesn't support the /users/{id}/lifecycle/expire_password endpoint. See Configure an Okta account management policy.

EXEC okta.users.users.expire_password 
@subdomain='{{ subdomain }}' --required
;

expire_password_with_temp_password

Expires the password and resets the user's password to a temporary password. This operation transitions the user status to PASSWORD_EXPIRED so that the user must change their password the next time that they sign in.
The user's password is reset to a temporary password that's returned, and then the user's password is expired.
If revokeSessions is included in the request with a value of true, the user's current outstanding sessions are revoked and require re-authentication.


If you have integrated Okta with your on-premises Active Directory (AD), then setting a user's password as expired in Okta also expires the password in AD.
When the user tries to sign in to Okta, delegated authentication finds the password-expired status in AD,
and the user is presented with the password-expired page where they can change their password.

EXEC okta.users.users.expire_password_with_temp_password 
@subdomain='{{ subdomain }}' --required, 
@revokeSessions={{ revokeSessions }}
;

reactivate_user

Reactivates a user.

Perform this operation only on users with a PROVISIONED or RECOVERY status.
This operation restarts the activation workflow if for some reason the user activation wasn't completed when using the activationToken from Activate User.

Users that don't have a password must complete the flow by completing the Reset password flow and MFA enrollment steps to transition the user to ACTIVE status.

If sendEmail is false, returns an activation link for the user to set up their account. The activation token can be used to create a custom activation link.

EXEC okta.users.users.reactivate_user 
@subdomain='{{ subdomain }}' --required, 
@sendEmail={{ sendEmail }}
;

reset_factors

Resets all factors for the specified user. All MFA factor enrollments return to the unenrolled state. The user's status remains ACTIVE. This link is present only if the user is currently enrolled in one or more MFA factors.

EXEC okta.users.users.reset_factors 
@subdomain='{{ subdomain }}' --required
;

reset_password

Resets a password. Generates a one-time token (OTT) that you can use to reset a user's password. You can automatically email the OTT link to the user or return the OTT to the API caller and distribute using a custom flow.

This operation transitions the user to the RECOVERY status. The user is then not able to sign in or initiate a forgot password flow until they complete the reset flow.

This operation provides an option to delete all the user's sessions. However, if the request is made in the context of a session owned by the specified user, that session isn't cleared.
> Note: You can also use this API to convert a user with the Okta credential provider to use a federated provider. After this conversion, the user can't directly sign in with a password.
> To convert a federated user back to an Okta user, use the default API call.

If an email address is associated with multiple users, keep in mind the following to ensure a successful password recovery lookup:
* Okta no longer includes deactivated users in the lookup.
* The lookup searches sign-in IDs first, then primary email addresses, and then secondary email addresses.
If sendEmail is false, returns a link for the user to reset their password.

EXEC okta.users.users.reset_password 
@sendEmail='{{ sendEmail }}' --required, 
@subdomain='{{ subdomain }}' --required, 
@revokeSessions={{ revokeSessions }}
;

suspend_user

Suspends a user. Perform this operation only on users with an ACTIVE status. The user has a SUSPENDED status when the process completes.

Suspended users can't sign in to Okta. They can only be unsuspended or deactivated. Their group and app assignments are retained.

EXEC okta.users.users.suspend_user 
@subdomain='{{ subdomain }}' --required
;

unlock_user

Unlocks a user with a LOCKED_OUT status or unlocks a user with an ACTIVE status that's blocked from unknown devices. Unlocked users have an ACTIVE status and can sign in with their current password.
> Note: This operation works with Okta-sourced users. It doesn't support directory-sourced accounts such as Active Directory.

EXEC okta.users.users.unlock_user 
@subdomain='{{ subdomain }}' --required
;

unsuspend_user

Unsuspends a user and returns them to the ACTIVE state. This operation can only be performed on users that have a SUSPENDED status.

EXEC okta.users.users.unsuspend_user 
@subdomain='{{ subdomain }}' --required
;

change_password

Updates a user's password by validating the user's current password.

This operation provides an option to delete all the sessions of the specified user. However, if the request is made in the context of a session owned by the specified user, that session isn't cleared.

You can only perform this operation on users in STAGED, ACTIVE, PASSWORD_EXPIRED, or RECOVERY status that have a valid password credential.

The user transitions to ACTIVE status when successfully invoked in RECOVERY status.

> Note: The Okta account management policy doesn't support the /users/{userId}/credentials/change_password endpoint. See Configure an Okta account management policy.

EXEC okta.users.users.change_password 
@subdomain='{{ subdomain }}' --required, 
@strict={{ strict }} 
@@json=
'{
"newPassword": "{{ newPassword }}", 
"oldPassword": "{{ oldPassword }}", 
"revokeSessions": {{ revokeSessions }}
}'
;

change_recovery_question

Updates a user's recovery question and answer credential by validating the user's current password.
You can only perform this operation on users in STAGED, ACTIVE, or RECOVERY status that have a valid password credential.

EXEC okta.users.users.change_recovery_question 
@subdomain='{{ subdomain }}' --required 
@@json=
'{
"password": "{{ password }}", 
"recovery_question": "{{ recovery_question }}"
}'
;

forgot_password

Starts the forgot password flow.

Generates a one-time token (OTT) that you can use to reset a user's password.

The user must validate their security question's answer when visiting the reset link. Perform this operation only on users with an ACTIVE status and
a valid recovery question credential.

> Note: If you have migrated to Identity Engine, you can allow users to recover passwords with any enrolled MFA authenticator. See Self-service account recovery.

If an email address is associated with multiple users, keep in mind the following to ensure a successful password recovery lookup:
* Okta no longer includes deactivated users in the lookup.
* The lookup searches sign-in IDs first, then primary email addresses, and then secondary email addresses.

If sendEmail is false, returns a link for the user to reset their password. This operation doesn't affect the status of the user.

EXEC okta.users.users.forgot_password 
@subdomain='{{ subdomain }}' --required, 
@sendEmail={{ sendEmail }}
;

forgot_password_set_new_password

Resets the user's password to the specified password if the provided answer to the recovery question is correct.
You must include the recovery question answer with the submission.

EXEC okta.users.users.forgot_password_set_new_password 
@subdomain='{{ subdomain }}' --required, 
@sendEmail={{ sendEmail }} 
@@json=
'{
"password": "{{ password }}", 
"recovery_question": "{{ recovery_question }}"
}'
;

revoke_user_sessions

Revokes all active identity provider sessions of the user. This forces the user to authenticate on the next operation. Optionally revokes OpenID Connect and OAuth refresh and access tokens issued to the user.

You can also clear the user's remembered factors for all devices using the forgetDevices parameter. See forgetDevices.
> Note: This operation doesn't clear the sessions created for web or native apps.

EXEC okta.users.users.revoke_user_sessions 
@subdomain='{{ subdomain }}' --required, 
@oauthTokens={{ oauthTokens }}, 
@forgetDevices={{ forgetDevices }}
;