POST /api/v1/users/{id}

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, Forgot Password, and Change Password endpoints.

Servers

https://{yourOktaDomain}

Path parameters

Name	Type	Required	Description
`id`	String	Yes	`id`, `login`, or `login shortname` (as long as it is unambiguous) of user

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Query parameters

Name	Type	Required	Description
`strict`	Boolean	No	If true, validates against minimum age and history password policy

Request body fields

Name	Type	Required	Description
`profile`	Object	No	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.
`profile.honorificSuffix`	String	No	Honorific suffix(es) of the User
`profile.postalAddress`	String	No	Mailing address component of the User's address
`profile.userType`	String	No	The property used to describe the organization-to-user relationship, such as employee or contractor
`profile.department`	String	No	Name of the User's department
`profile.displayName`	String	No	Name of the User suitable for display to end users
`profile.state`	String	No	The state or region component of the User's address (`region`)
`profile.zipCode`	String	No	The ZIP code or postal code component of the User's address (`postalCode`)
`profile.city`	String	No	The city or locality of the User's address (`locality`)
`profile.middleName`	String	No	The middle name of the user
`profile.timezone`	String	No	The User's time zone
`profile.costCenter`	String	No	Name of the cost center assigned to a user
`profile.email`	String	No	The primary email address of the user. For validation, see RFC 5322 Section 3.2.3.
`profile.employeeNumber`	String	No	The organization or company assigned unique identifier for the user
`profile.preferredLanguage`	String	No	The User's preferred written or spoken language. For validation, see RFC 7231 Section 5.3.5.
`profile.locale`	String	No	The User's default location for purposes of localizing items such as currency, date time format, numerical representations, and so on. A locale value is a concatenation of the ISO 639-1 two-letter language code, an underscore, and the ISO 3166-1 two-letter country code. For example, en_US specifies the language English and country US. This value is `en_US` by default.
`profile.title`	String	No	The User's title, such as Vice President
`profile.secondEmail`	String	No	The secondary email address of the User typically used for account recovery. For validation, see RFC 5322 Section 3.2.3.
`profile.managerId`	String	No	The `id` of the User's manager
`profile.division`	String	No	Name of the User's division
`profile.streetAddress`	String	No	The full street address component of the User's address
`profile.manager`	String	No	The `displayName` of the User's manager
`profile.nickName`	String	No	The casual way to address the User in real life
`profile.organization`	String	No	Name of the the User's organization
`profile.countryCode`	String	No	The country name component of the User's address (`country`). For validation, see ISO 3166-1 alpha 2 "short" code format.
`profile.honorificPrefix`	String	No	Honorific prefix(es) of the user, or title in most Western languages
`profile.lastName`	String	No	The family name of the User (`familyName`)
`profile.mobilePhone`	String	No	The mobile phone number of the user
`profile.firstName`	String	No	Given name of the User (`givenName`)
`profile.login`	String	No	The unique identifier for the User (`username`). For validation, see Login pattern validation. Every user within your Okta org must have a unique identifier for a login. This constraint applies to all users you import from other systems or applications such as Active Directory. Your organization is the top-level namespace to mix and match logins from all your connected applications or directories. Careful consideration of naming conventions for your login identifier will make it easier to onboard new applications in the future. Logins are not considered unique if they differ only in case and/or diacritical marks. If one of your users has a login of Isaac.Brock@example.com, there cannot be another user whose login is isaac.brock@example.com, nor isáàc.bröck@example.com. Okta has a default ambiguous name resolution policy for usernames that include @-signs. (By default, usernames must be formatted as email addresses and thus always include @-signs. You can remove that restriction using either the Admin Console or the Schemas API (opens new window).) Users can sign in with their non-qualified short name (for example: isaac.brock with username isaac.brock@example.com) as long as the short name is still unique within the organization. maxLength: 100
`profile.primaryPhone`	String	No	The primary phone number of the User such as a home number
`profile.profileUrl`	String	No	The URL of the User's online profile. For example, a web page. See URL.
`realmId`	String	No	The ID of the Realm in which the User is residing
`credentials`	Object	No	Specifies primary authentication and recovery credentials for a User. Credential types and requirements vary depending on the provider and security policy of the org.
`credentials.provider`	Object	No	Specifies the authentication provider that validates the User's password credential. The User's current provider is managed by the Delegated Authentication settings for your organization. The provider object is read-only.
`credentials.provider.name`	String	No	The name of the authentication provider
`credentials.provider.type`	String	No	The type of authentication provider Possible values: `"ACTIVE_DIRECTORY"` `"OKTA"` `"LDAP"` `"FEDERATION"` `"IMPORT"` `"SOCIAL"`
`credentials.recovery_question`	Object	No	Specifies a secret question and answer that's validated (case insensitive) when a User forgets their password or unlocks their account. The answer property is write-only.
`credentials.recovery_question.answer`	String	No	The answer to the recovery question
`credentials.recovery_question.question`	String	No	The recovery question
`credentials.password`	Object	No	Specifies a password for a user. When a User has a valid password, imported hashed password, or password hook, and a response object contains a password credential, then the password object is a bare object without the value property defined (for example, `password: {}`). This indicates that a password value exists. You can modify password policy requirements in the Admin Console by editing the Password authenticator: Security > Authenticators > Password (or for Okta Classic orgs, use Security > Authentication > Password). For information on defaults and configuring your password policies, see Configure the password authenticator in the help documentation.
`credentials.password.hash`	Object	No	Specifies a hashed password to import into Okta. This allows an existing password to be imported into Okta directly from some other store. Okta supports the BCRYPT, SHA-512, SHA-256, SHA-1, MD5, and PBKDF2 hash functions for password import. A hashed password may be specified in a Password object when creating or updating a user, but not for other operations. See Create User with Imported Hashed Password for information on using this object when creating a user. When updating a User with a hashed password, the User must be in the `STAGED` status.
`credentials.password.hash.digestAlgorithm`	String	No	Algorithm used to generate the key. Only required for the PBKDF2 algorithm. Possible values: `"SHA512_HMAC"` `"SHA256_HMAC"`
`credentials.password.hash.keySize`	Integer	No	Size of the derived key in bytes. Only required for PBKDF2 algorithm.
`credentials.password.hash.algorithm`	String	No	The algorithm used to generate the hash using the password (and salt, when applicable). Possible values: `"BCRYPT"` `"PBKDF2"` `"MD5"` `"SHA-256"` `"SHA-512"` `"SHA-1"`
`credentials.password.hash.iterationCount`	Integer	No	The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.
`credentials.password.hash.value`	String	No	For SHA-512, SHA-256, SHA-1, MD5, and PBKDF2, this is the actual base64-encoded hash of the password (and salt, if used). This is the Base64-encoded `value` of the SHA-512/SHA-256/SHA-1/MD5/PBKDF2 digest that was computed by either pre-fixing or post-fixing the `salt` to the `password`, depending on the `saltOrder`. If a `salt` was not used in the `source` system, then this should just be the Base64-encoded `value` of the password's SHA-512/SHA-256/SHA-1/MD5/PBKDF2 digest. For BCRYPT, this is the actual Radix-64 encoded hashed password.
`credentials.password.hash.saltOrder`	String	No	Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.
`credentials.password.hash.workFactor`	Integer	No	Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.
`credentials.password.hash.salt`	String	No	Only required for salted hashes. For BCRYPT, this specifies Radix-64 as the encoded salt used to generate the hash, which must be 22 characters long. For other salted hashes, this specifies the Base64-encoded salt used to generate the hash.
`credentials.password.hook`	Object	No	Specify a password import inline hook to trigger verification of the User's password the first time the User signs in. This allows an existing password to be imported into Okta directly from some other store.
`credentials.password.hook.type`	String	No	The type of password inline hook. Currently, must be set to default.
`credentials.password.value`	String	No	Specifies the password for a user. The Password Policy validates this password.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.