User Credentials

The User Credentials API provides operations to manage user credentials in your org.

Update password
CORS
OAuth 2.0: okta.users.manage

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.

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
query Parameters
strict
boolean
Default: false

If true, validates against password minimum age policy

Request Body schema: application/json
required
object (PasswordCredential)

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.

object (PasswordCredentialHash)

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 the Create user with imported hashed password section in the Users API description. When updating a user with a hashed password, the usermust be in the STAGED status.

algorithm
string (PasswordCredentialHashAlgorithm)

The algorithm used to generate the hash using the password (and salt, when applicable).

Enum: "BCRYPT" "MD5" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)

Algorithm used to generate the key. Only required for the PBKDF2 algorithm.

Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer

The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.

keySize
integer

Size of the derived key in bytes. Only required for PBKDF2 algorithm.

salt
string

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.

saltOrder
string

Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.

value
string

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.

workFactor
integer [ 1 .. 20 ]

Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.

object (PasswordCredentialHook)

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.

type
string

The type of password inline hook. Currently, must be set to default.

value
string <password>

Specifies the password for a user. The password policy validates this password.

object (PasswordCredential)

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.

object (PasswordCredentialHash)

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 the Create user with imported hashed password section in the Users API description. When updating a user with a hashed password, the usermust be in the STAGED status.

algorithm
string (PasswordCredentialHashAlgorithm)

The algorithm used to generate the hash using the password (and salt, when applicable).

Enum: "BCRYPT" "MD5" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)

Algorithm used to generate the key. Only required for the PBKDF2 algorithm.

Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer

The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.

keySize
integer

Size of the derived key in bytes. Only required for PBKDF2 algorithm.

salt
string

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.

saltOrder
string

Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.

value
string

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.

workFactor
integer [ 1 .. 20 ]

Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.

object (PasswordCredentialHook)

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.

type
string

The type of password inline hook. Currently, must be set to default.

value
string <password>

Specifies the password for a user. The password policy validates this password.

revokeSessions
boolean
Default: false

When set to true, revokes all user sessions, except for the current session

Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/change_password
Request samples
application/json
{
  • "oldPassword": {
    • "value": "tlpWENT2m"
    },
  • "newPassword": {
    • "value": "uTVM,TPw55"
    },
  • "revokeSessions": true
}
Response samples
application/json
{
  • "password": { },
  • "recovery_question": {
    • "question": "Who's a major player in the cowboy scene?"
    },
  • "provider": {
    • "type": "OKTA",
    • "name": "OKTA"
    }
}

Update recovery question
CORS
OAuth 2.0: okta.users.manage

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.

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
Request Body schema: application/json
required
object (PasswordCredential)

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.

object (PasswordCredentialHash)

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 the Create user with imported hashed password section in the Users API description. When updating a user with a hashed password, the usermust be in the STAGED status.

algorithm
string (PasswordCredentialHashAlgorithm)

The algorithm used to generate the hash using the password (and salt, when applicable).

Enum: "BCRYPT" "MD5" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"
digestAlgorithm
string (DigestAlgorithm)

Algorithm used to generate the key. Only required for the PBKDF2 algorithm.

Enum: "SHA256_HMAC" "SHA512_HMAC"
iterationCount
integer

The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.

keySize
integer

Size of the derived key in bytes. Only required for PBKDF2 algorithm.

salt
string

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.

saltOrder
string

Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.

value
string

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.

workFactor
integer [ 1 .. 20 ]

Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.

object (PasswordCredentialHook)

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.

type
string

The type of password inline hook. Currently, must be set to default.

value
string <password>

Specifies the password for a user. The password policy validates this password.

object (RecoveryQuestionCredential)

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.

answer
string [ 1 .. 100 ]

The answer to the recovery question

question
string [ 1 .. 100 ]

The recovery question

Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/change_recovery_question
Request samples
application/json
{
  • "password": {
    • "value": "tlpWENT2m"
    },
  • "recovery_question": {
    • "question": "How many roads must a man walk down?",
    • "answer": "forty two"
    }
}
Response samples
application/json
{
  • "password": { },
  • "recovery_question": {
    • "question": "How many roads must a man walk down?"
    },
  • "provider": {
    • "type": "OKTA",
    • "name": "OKTA"
    }
}

Start forgot password flow
CORS
OAuth 2.0: okta.users.manage

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. This operation can only be performed 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.

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
query Parameters
sendEmail
boolean
Default: true

Sends a forgot password email to the User if true

Responses
200

Reset URL

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/credentials/forgot_password
Request samples 
Response samples 
application/json
{}
Reset password with recovery question
CORS
OAuth 2.0: okta.users.manage
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.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
query Parameters
sendEmail
boolean
 Default:  true
 
Request Body schema: application/json
required
object (PasswordCredential) 
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.


 
object (PasswordCredentialHash) 
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 the Create user with imported hashed password section in the Users API description. When updating a user with a hashed password, the usermust be in the STAGED status.


 
algorithm
string (PasswordCredentialHashAlgorithm) 
The algorithm used to generate the hash using the password (and salt, when applicable).


 Enum: "BCRYPT" "MD5" "PBKDF2" "SHA-1" "SHA-256" "SHA-512"  
digestAlgorithm
string (DigestAlgorithm) 
Algorithm used to generate the key. Only required for the PBKDF2 algorithm.


 Enum: "SHA256_HMAC" "SHA512_HMAC"  
iterationCount
integer
The number of iterations used when hashing passwords using PBKDF2. Must be >= 4096. Only required for PBKDF2 algorithm.


 
keySize
integer
Size of the derived key in bytes. Only required for PBKDF2 algorithm.


 
salt
string
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.


 
saltOrder
string
Specifies whether salt was pre- or postfixed to the password before hashing. Only required for salted algorithms.


 
value
string
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.


 
workFactor
integer  [ 1 .. 20 ] 
Governs the strength of the hash and the time required to compute it. Only required for BCRYPT algorithm.


 
object (PasswordCredentialHook) 
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.


 
type
string
The type of password inline hook. Currently, must be set to default.


 
value
string <password> 
Specifies the password for a user. The password policy validates this password.


 
object (RecoveryQuestionCredential) 
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.


 
answer
string  [ 1 .. 100 ] 
The answer to the recovery question


 
question
string  [ 1 .. 100 ] 
The recovery question


 
Responses 
200
Credentials


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/credentials/forgot_password_recovery_question
Request samples 
application/json
{
  • "password": {
    • "value": "uTVM,TPw55"
    },
  • "recovery_question": {
    • "answer": "Annie Oakley"
    }
}
Response samples 
application/json
{
  • "password": { },
  • "recovery_question": {
    • "question": "Who's a major player in the cowboy scene?"
    },
  • "provider": {
    • "type": "OKTA",
    • "name": "OKTA"
    }
}
Expire password
CORS
OAuth 2.0: okta.users.manage
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.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/expire_password
Request samples 
Response samples 
application/json
{}
Expire password with temporary password
CORS
OAuth 2.0: okta.users.manage
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.
User's Password is reset to a temporary password that is 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.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
query Parameters
revokeSessions
boolean
 Default:  false
Revokes the User's existing sessions if true


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/expire_password_with_temp_password
Request samples 
Response samples 
application/json
{
  • "tempPassword": "F46gy7X4"
}
Reset password
CORS
OAuth 2.0: okta.users.manage
Resets 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.
    • 



Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
query Parameters
sendEmail
required
boolean
 
revokeSessions
boolean
 Default:  false
Revokes all User sessions, except for the current session, if set to true


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/lifecycle/reset_password
Request samples 
Response samples 
application/json
{}