The Okta Authentication API provides operations to authenticate users, perform multifactor enrollment and verification, recover forgotten passwords, and unlock accounts. It can be used as a standalone API to provide the identity layer on top of your existing application, or it can be integrated with the Okta Sessions API to obtain an Okta session cookie and access apps within Okta. Show
The API is targeted for developers who want to build their own end-to-end login experience to replace the built-in Okta login experience and addresses the following key scenarios:
Application typesThe behavior of the Okta Authentication API varies depending on the type of your application and your org's security policies such as the global session policy, the MFA Enrollment Policy, or the Password Policy.
Public applicationA public application is an application that anonymously starts an authentication or recovery transaction without an API token, such as the Okta Sign-In Widget. Public applications are aggressively rate-limited to prevent abuse and require primary authentication to be successfully completed before releasing any metadata about a user. Trusted applicationTrusted applications are backend applications that act as authentication broker or login portal for your Okta organization and may start an authentication or recovery transaction with an administrator API token. Trusted apps may implement their own recovery flows and primary authentication process and may receive additional metadata about the user before primary authentication has successfully completed.
Get started with authentication
Authentication operationsPrimary authenticationPOST /api/v1/authn Every authentication transaction starts with primary authentication which validates a user's primary password credential. Password Policy, MFA Policy, and Sign-On Policy are evaluated during primary authentication to determine if the user's password is expired, a Factor should be enrolled, or additional verification is required. The transaction state of the response depends on the user's status, group memberships and assigned policies.
The requests and responses vary depending on the application type, and whether a password expiration warning is sent:
Request parameters for primary authenticationAs part of the authentication call either the username and password or the token parameter must be provided.
Options objectThe authentication transaction state machine can be modified via the following opt-in features:
Context objectThe context object allows trusted web applications such as an external portal to pass additional context for the authentication or recovery transaction.
Device Token best practicesUse the following recommendations as
guidelines for generating and storing a Web apps Native apps Response parametersAuthentication Transaction object with the current state for the authentication transaction
Primary authentication with public applicationAuthenticates a user with username/password credentials via a public application Request example for primary authentication with public applicationResponse example for primary authentication with public application (success)Users with a valid password not assigned to a Sign-On Policy with additional verification requirements will successfully complete the authentication transaction. Response example for primary authentication with public application (invalid credentials)
Response example for primary authentication with public application (locked out)Primary authentication requests for a user with Response example for primary authentication with public application and hide lockout failures (Default)If the user's password policy is configured to hide lockout failures, a Response example for primary authentication with public application and show lockout failuresIf the user's password policy is configure to show lockout failures, the authentication transaction completes with Response example for primary authentication with public application and expired passwordUser must change their expired password to complete the authentication transaction.
Response example for primary authentication with public application (Factor challenge)User is assigned to a Sign-On Policy that requires additional verification and must select and verify a previously enrolled
Factor by Response example for primary authentication with public application (Factor enroll)User is assigned to a MFA Policy that requires enrollment during sign-in and must select a Factor to enroll to complete the authentication transaction.
Primary authentication with trusted applicationAuthenticates a user through a trusted application or proxy that overrides the client request context Notes:
Request example for trusted applicationResponse example for trusted applicationPrimary authentication with activation tokenAuthenticates a user through a trusted application or proxy that overrides the client request context Notes:
Request example for activation tokenResponse example for activation token (success - user with password, no MFA)Response example for activation token (success - user with password and configured MFA)Response example for activation token (success - user without password)In the case where the user was created without credentials the response will trigger the workflow to set the user's password. After the password is configured, depending on the MFA setting, the workflow continues with MFA enrollment or a successful authentication completes. Response example for activation token (failure - invalid or expired token)Primary authentication with device fingerprintingInclude the
Specifying your own device fingerprint in the
Device fingerprint best practicesUse the following recommendations as guidelines for generating and storing a device fingerprint in the Web apps Native apps Request example for device fingerprintingResponse example for device fingerprintingPrimary authentication with password expiration warningAuthenticates a user with a password that is about to expire. The user should change their password to complete the authentication transaction but can choose to skip it. Notes:
Request example for password expiration warningResponse example for password expiration warningSP-initiated step-up authenticationEarly Access Notes:
Every step-up transaction starts with the user accessing an application. If step-up authentication is required, Okta redirects the user to the custom sign-in page with state token as a request parameter. For example, if the custom sign-in page is set as
Step-up authentication without Okta sessionRequest example for step-up authentication without Okta session (get transaction state)Response example for step-up authentication without Okta sessionRequest example for step-up authentication without Okta session (perform primary authentication)Primary authentication has to be completed by using the value of stateToken request parameter passed to custom sign-in page.
Response example for step-up authentication without Okta session when MFA isn't required
Step-up authentication with Okta sessionRequest example to get transaction state for step-up authentication with Okta sessionResponse example for Factor enroll for step-up authentication with Okta sessionThe user is assigned to an MFA Policy that requires enrollment during the sign-in process and must select a Factor to enroll to complete the authentication transaction.
Response example for Factor challenge for step-up authentication with Okta sessionUser is
assigned to a global session policy or an authentication policy that requires additional verification and must select and verify a previously enrolled Factor by Response example after authentication and MFA are complete for step-up authentication with Okta session
IDP-initiated step-up authenticationPOST /api/v1/authn Early Access Authenticates a user for signing in to the specified application Notes:
Request example for IDP-initiated step-up authentication
Response example when MFA isn't required
Response example for Factor enrollThe user is assigned to an MFA Policy that requires enrollment during the sign-in process and must select a Factor to enroll to complete the authentication transaction.
Response example for Factor challengeUser is assigned to a Sign-on Policy or App Sign-on Policy that requires additional verification and must select and verify a previously enrolled Factor by Response example for invalid or unknown applicationResponse example for unsupported applicationChange passwordPOST /api/v1/authn/credentials/change_password Changes a user's password by providing the existing password and the new password for authentication transactions with either the This operation provides an option to revoke all the sessions of the specified user, except for the current session, if the endpoint is called by the user.
Request parameters for change password
Response parameters for change passwordAuthentication Transaction object with the current state for the authentication transaction If the If the
Request example for change passwordResponse example for change passwordMultifactor Authentication operationsYou can enroll, activate, manage, and verify factors inside the authentication context with
Enroll FactorPOST /api/v1/authn/factors CORS Enrolls a user with a Factor assigned by their MFA Policy
Request parameters for enroll Factor
Response parameters for enroll FactorAuthentication Transaction object with the current state for the authentication transaction
Enroll Okta Security Question FactorEnrolls a user with the Okta
Request example for enroll Okta Security Question FactorResponse example for enroll Okta Security Question FactorEnroll Okta SMS FactorEnrolls a user with the Okta Request example for enroll Okta SMS FactorResponse example for enroll Okta SMS FactorResend SMS as part of enrollmentUse the Request example for resend SMS Enroll Okta Call FactorEnrolls a user with the Okta Request example for enroll Okta Call FactorResponse example for enroll Okta Call FactorResend voice call as part of enrollmentUse the Request example for resend voice call Enroll Okta Email FactorEnrolls a user with the Okta Request example for enroll Okta Email FactorResponse example for enroll Okta Email FactorResend email as part of enrollmentUse the Enroll Okta Verify TOTP FactorEnrolls a user with the Okta
Request example for enroll Okta Verify TOTP FactorResponse example for enroll Okta Verify TOTP FactorEnroll Okta Verify Push FactorEnrolls a user with the Okta verify Use the published activation links to embed the QR code or distribute an
activation
Request example for enroll Okta Verify Push FactorResponse example for enroll Okta Verify Push FactorEnroll Google Authenticator FactorEnrolls a user with the Google Request example for enroll Google Authenticator factorResponse example for enroll Google Authenticator factorEnroll RSA SecurID factorEnrolls a user with an RSA SecurID factor and a token profile. RSA tokens must be verified with the current pin+passcode as part of the enrollment request. Request example for enroll RSA SecurID FactorResponse example for enroll RSA SecurID FactorEnroll Symantec VIP FactorEnrolls a user with a Symantec VIP Factor and a token profile. Symantec tokens must be verified with the current and next passcodes as part of the enrollment request. Request example for enroll Symantec VIP FactorResponse example for enroll Symantec VIP FactorEnroll YubiKey FactorEnrolls a user with a Yubico Factor (YubiKey). YubiKeys must be verified with the current passcode as part of the enrollment request. Request example for enroll YubiKey FactorResponse example for enroll YubiKey FactorEnroll Duo FactorThe enrollment process starts with an enrollment request to Okta, then continues with the Duo widget that is embedded in the page. The page needs to create an iframe with the name Request example for enroll Duo FactorResponse example for enroll Duo FactorFull page example for Duo enrollmentIn this example we put all of the elements together in the html page. Activation poll request exampleVerifies successful authentication and obtains a session token Activation poll response exampleEnroll U2F FactorEnrolls a user with a U2F Factor. The
enrollment process starts with getting an
Enroll U2F request exampleEnroll U2F response exampleEnroll WebAuthn Factor
Enrolls a user with a WebAuthn Factor. The enrollment process starts with getting the WebAuthn credential creation options, which are used to help select an appropriate authenticator using the WebAuthn API. This authenticator then generates an enrollment attestation that may be used to register the authenticator for the user. Enroll WebAuthn request parameters
Enroll WebAuthn response parametersIn the embedded resources object, the For more information about these credential creation options, see the WebAuthn spec for PublicKeyCredentialCreationOptions (opens new window).
Enroll WebAuthn request exampleEnroll WebAuthn response exampleEnroll Custom HOTP FactorEnrollment via the Authentication API is currently not supported for Custom HOTP Factor. Please refer to the Factors API documentation if you would like to enroll users for this type of Factor. Activate FactorPOST /api/v1/authn/factors/${factorId}/lifecycle/activate CORS The
Activate TOTP FactorActivates a
Request parameters for activate TOTP Factor
Response parameters for activate TOTP FactorAuthentication Transaction object with the current state for the authentication transaction If the passcode is invalid, you receive a Activate TOTP request exampleActivate TOTP response exampleActivate SMS FactorActivates an Activate SMS Factor request parameters
Activate SMS Factor response parametersAuthentication Transaction object with the current state for the authentication transaction If the passcode is invalid, you receive a Activate SMS Factor request exampleActivate SMS Factor response exampleActivate Call FactorActivates a Activate Call Factor request parameters
Activate Call Factor response parametersAuthentication Transaction object with the current state for the authentication transaction If the passcode is invalid, you receive a Activate Call Factor request exampleActivate Call Factor response exampleActivate Email FactorActivates an Activate Email Factor request parameters
Activate Email Factor response parametersAuthentication Transaction object with the current state for the authentication transaction. If the passcode is invalid, you receive a Activate Email Factor request exampleActivate Email Factor response exampleActivate Push FactorActivation of Activations have a short lifetime (minutes) and Activate Push Factor request parameters
Activate Push Factor response parametersAuthentication Transaction object with the current state for the authentication transaction Activate Push Factor request exampleActivate Push Factor response example (waiting)
Activate Push Factor response example (success)Activate Push Factor response example (timeout)
Poll for Push Factor activationAfter the push notification is sent to the user's device, we need to know when the user completes the activation. This is done by polling the "poll" link. Poll for Push request example Poll for Push response exampleSend activation linksSends an activation email or SMS when the user is unable to scan the QR code provided as part of an Okta Verify transaction. If for any reason the user can't scan the QR code, they can use the link provided in email or SMS to complete the transaction. Send activation links request example (email) Send activation links request example (SMS) Send activation links response example Activate U2F FactorActivation gets the registration information from the U2F token using the API and passes it to Okta. Get registration information from U2F token by calling the U2F JavaScript library methodActivate
a Activate U2F request parameters
Activate U2F response parametersAuthentication Transaction object with the current state for the authentication transaction If the registration nonce is invalid or if registration data is invalid, you receive a Activate U2F request exampleActivate U2F response exampleActivate WebAuthn FactorActivation gets the registration information from the WebAuthn assertion using the API and passes it to Okta. Get registration information from WebAuthn assertion by calling the WebAuthn JavaScript libraryActivate a Activate WebAuthn request parameters
Activate WebAuthn response parametersAuthentication Transaction object with the current state for the authentication transaction If the attestation nonce is invalid, or if the attestation or client data are invalid, you receive a
Activate WebAuthn request exampleActivate WebAuthn response exampleVerify FactorVerifies an enrolled Factor for an authentication transaction with the
Verify Security Question FactorPOST /api/v1/authn/factors/${factorId}/verify CORS Verifies an answer to a Request parameters for verify Security Question Factor
Response parameters for verify Security Question FactorAuthentication Transaction object with the current state for the authentication transaction If the Request example for verify Security Question FactorResponse example for verify Security Question FactorVerify SMS FactorPOST /api/v1/authn/factors/${factorId}/verify CORS Request parameters for verify SMS Factor
Response parameters for verify SMS FactorAuthentication Transaction object with the current state for the authentication transaction If the Send SMS challenge (OTP)Omit Resend SMS challengeUse the Request example for resend SMS Verify SMS challenge (OTP)Specify Verify Call FactorPOST /api/v1/authn/factors/${factorId}/verify CORS Request parameters for verify Call Factor
Response parameters for verify Call FactorAuthentication Transaction object with the current state for the authentication transaction If the Send Voice Call challenge (OTP)Omit Resend voice call challengeUse the Request example for resend voice call Verify Call challenge (OTP)Specify Verify TOTP FactorPOST /api/v1/authn/factors/${factorId}/verify CORS Verifies an OTP for a
Request parameters for verify TOTP Factor
Response parameters for verify TOTP FactorAuthentication Transaction object with the current state for the authentication transaction If the passcode is invalid, you receive a Verify Push FactorPOST /api/v1/authn/factors/${factorId}/verify CORS Sends an asynchronous push notification (challenge) to the device for the user to approve or reject. The Request parameters for verify Push Factor
Okta Verify Push details pertaining to auto-push
Request example for verify Push FactorResponse example (waiting)
Response example (waiting for 3-number verification challenge response)
Response example (approved)Response example (rejected)Response example (timeout)Resend push notificationUse the Verify Duo FactorVerification of the Duo Factor is implemented as an integration with Duo widget. The process is very similar to the enrollment where the widget is embedded in an iframe - "duo_iframe". Verification starts with request to the Okta API, then continues with a Duo widget that handles the actual verification. We need to pass the state token as hidden object in "duo_form". The authentication completes with call to poll link to verify the state and obtain session token. Request example for verify Duo FactorResponse example for verify Duo FactorSample for Duo iFrameVerification poll request exampleVerification poll response exampleVerify U2F fFactorPOST /api/v1/authn/factors/${factorId}/verify CORS
Start verification to get challenge nonceVerification of the U2F Factor starts with getting the challenge nonce and U2F token details and then using the client-side JavaScript API to get the signed assertion from the U2F token. Request example for verify U2F FactorResponse example for verify U2F FactorGet the signed assertion from the U2F tokenPost the signed assertion to Okta to complete verificationRequest parameters for verify U2F Factor
Request example for signed assertionResponse of U2F verification exampleVerify WebAuthn FactorPOST /api/v1/authn/factors/${factorIdOrFactorType}/verify CORS Verifies a user with a WebAuthn Factor. The verification process starts with getting the WebAuthn credential request options, which are used to help select an appropriate authenticator using the WebAuthn API. This authenticator then generates an assertion that may be used to verify the user.
Start verification to get challenge nonceVerification of the WebAuthn Factor starts with getting the WebAuthn credential request details (including the challenge nonce) then using the client-side JavaScript API to get the signed assertion from the WebAuthn authenticator. For more information about these credential request options, see the WebAuthn spec for PublicKeyCredentialRequestOptions (opens new window). Request example for verify WebAuthn FactorResponse example for verify WebAuthn Factor by |
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
authenticatorData | base64-encoded authenticator data from the WebAuthn authenticator | Body | String | TRUE |
clientData | base64-encoded client data from the WebAuthn authenticator | Body | String | TRUE |
factorId | id of Factor
| URL | String | TRUE (factorId OR factorType required)
|
factorType | factorType of Factor; for WebAuthn, it is webauthn
| URL | String | TRUE (factorId OR factorType required)
|
rememberDevice | user's decision to remember the device | URL | Boolean | FALSE |
signatureData | base64-encoded signature data from the WebAuthn authenticator | Body | String | TRUE |
stateToken | state token for the current transaction | Body | String | TRUE |
Request example for signed assertion
Response of WebAuthn verification example
Recovery operations
Forgot password
POST /api/v1/authn/recovery/password
Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user's password
- Forgot Password with Email Factor
- Forgot Password with SMS Factor
- Forgot Password with Call Factor
- Forgot Password with Trusted Application
Note: Self-service password reset (forgot password) must be permitted via the user's assigned password policy to use this operation.
Request parameters for forgot password
Parameter | Description | Param Type | DataType | Required | MaxLength |
---|---|---|---|---|---|
factorType | Recovery Factor to use for primary authentication | Body | EMAIL or SMS or CALL
| FALSE | |
username | User's non-qualified short-name (for example: dade.murphy) or unique fully-qualified sign-in name (for example: ) | Body | String | TRUE |
Note: A valid
factorType
is required for requests without an API token with administrator privileges. For more information, see Forgot Password with Trusted Application.
Note: The optional parameter
relayState
can be included as part of the body in the Forgot Password request.relayState
is a link to a site where the user will be redirected when the password recovery operation completes. The 'relayState' link must point to a trusted origin.
The response is different, depending on whether the request is for a public application or a trusted application.
Response parameters for public application for forgot password
The
Recovery Transaction object with RECOVERY_CHALLENGE
status for the new recovery transaction
You will always receive a Recovery Transaction response even if the requested username
is not a valid identifier to prevent information disclosure.
Response parameters for trusted application for forgot password
The Recovery Transaction object with an issued recoveryToken
that can be distributed to the end user
You will receive a 403 Forbidden
status code if the username
requested is not valid.
Forgot password with Email Factor
Starts a new password recovery transaction for the email Factor:
- You must specify a user identifier (
username
) but no password in the request. - If the request is successful, Okta sends a recovery email asynchronously to the user's primary and secondary email address with a recovery token so the user can complete the transaction.
Primary authentication of a user's recovery credential (for example:
EMAIL
or SMS
) hasn't completed when this request is sent. The user is pending validation.
Okta provides security in the following ways:
- Since the recovery email is distributed out-of-band and may be viewed on a different user agent or device, this operation does not return a state token and does not have a
next
link. - Okta doesn't publish additional metadata about the user until primary authentication has successfully completed. See the Response Example in this section for details.
Request example for forgot password with Email Factor
Response example for forgot password with Email Factor
Forgot password with SMS Factor
Starts a new password recovery
transaction with a user identifier (username
) and asynchronously sends a SMS OTP (challenge) to the user's mobile phone. This operation will transition the recovery transaction to the RECOVERY_CHALLENGE
state and wait for the user to verify the OTP.
Note: Primary authentication of a user's recovery credential (for example: email or SMS) hasn't yet completed. Okta doesn't publish additional metadata about the user until primary authentication has successfully completed.
Note: SMS recovery Factor must be enabled via the user's assigned password policy to use this operation.
Request example for forgot password with SMS Factor
Response example for forgot password with SMS Factor
Forgot password with Call Factor
Starts a new password recovery transaction with a user identifier (username
) and asynchronously sends a Voice Call with OTP (challenge) to the user's phone. This operation transitions the recovery transaction to the RECOVERY_CHALLENGE
state and wait for user to
verify the OTP.
Notes:
- Primary authentication of a user's recovery credential (for example: email or SMS or Voice Call) hasn't yet completed.
- Okta won't publish additional metadata about the user until primary authentication has successfully completed.
- Voice Call recovery Factor must be enabled via the user's assigned password policy to use this operation.
Request example for forgot password with Call Factor
Response example for forgot password with Call Factor
Forgot password with trusted application
Allows a trusted application such as an external portal to implement its own primary authentication process and directly obtain a recovery token for a user given just the user's identifier
Note: Directly obtaining a
recoveryToken
is a highly privileged operation that requires an administrator API token and should be restricted to trusted web applications. Anyone that obtains arecoveryToken
for a user and knows the answer to a user's recovery question can reset their password or unlock their account.
Note: The public IP address of your trusted application must be allowed as a gateway IP address to forward the user agent's original IP address with the
X-Forwarded-For
HTTP header.
Request example for forgot password with trusted application
Response example for forgot password with tusted application
Unlock account
POST /api/v1/authn/recovery/unlock
Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user's account
- Unlock Account with Email Factor
- Unlock Account with SMS Factor
- Unlock Account with Trusted Application
Note: Self-service unlock must be permitted via the user's assigned password policy to use this operation.
Request parameters for unlock account
Parameter | Description | Param Type | DataType | Required | Max Length |
---|---|---|---|---|---|
factorType | Recovery Factor to use for primary authentication | Body | EMAIL or SMS
| FALSE | |
username | User's non-qualified short-name (for example: dade.murphy) or unique fully-qualified sign-in name (for example: ) | Body | String | TRUE |
Note: A valid
factorType
is required for requests without an API token with administrator privileges. (See Unlock Account with Trusted Application).
Response parameter public application for unlock account
Recovery Transaction object with RECOVERY_CHALLENGE
status for the new recovery transaction
You always receive a Recovery Transaction response, even if the requested username
isn't a valid identifier to prevent information disclosure.
Response parameter trusted application for unlock account
Recovery Transaction object with an issued recoveryToken
that can be distributed to the end user
You receive a 403 Forbidden
status code if the username
requested is not valid.
Unlock account with Email Factor
Starts a new unlock recovery
transaction with a user identifier (username
) and asynchronously sends a recovery email to the user's primary and secondary email address with a recovery token that can be used to complete the transaction
Since the recovery email is distributed out-of-band and may be viewed on a different user agent or device, this operation does not return a
state token and does not have a next
link.
Notes:
- Primary authentication of a user's recovery credential (e.g
EMAIL
orSMS
) hasn't yet completed. - Okta will not publish additional metadata about the user until primary authentication has successfully completed.
Request example for Email Factor
Response example for Email Factor
Unlock account with SMS Factor
Starts a new unlock recovery transaction with a user identifier (username
) and asynchronously sends an SMS OTP (challenge) to the user's mobile phone. This operation transitions the recovery transaction to the RECOVERY_CHALLENGE
state and waits for the user to verify the OTP.
Notes:
- Primary authentication of a user's recovery credential (e.g email or SMS) hasn't yet completed.
- Okta won't publish additional metadata about the user until primary authentication has successfully completed.
- SMS recovery Factor must be enabled via the user's assigned password policy to use this operation.
Request example for unlock account with SMS Factor
Response example for unlock account with SMS Factor
Unlock account with trusted application
Allows a trusted application such as an external portal to implement its own primary authentication process and directly obtain a recovery token for a user given just the user's identifier
Notes:
Directly obtaining a
recoveryToken
is a highly privileged operation that requires an administrator API token and should be restricted to trusted web applications. Anyone that obtains arecoveryToken
for a user and knows the answer to a user's recovery question can reset their password or unlock their account.The public IP address of your trusted application must be allowed as a gateway IP address to forward the user agent's original IP address with the
X-Forwarded-For
HTTP header.
Request example for unlock account with SMS Factor (trusted application)
Response example for unlock account with SMS Factor (trusted application)
Verify recovery Factor
Verify SMS recovery Factor
POST /api/v1/authn/recovery/factors/sms/verify
Verifies a SMS OTP (passCode
) sent to the user's mobile phone for primary authentication for a recovery transaction with RECOVERY_CHALLENGE
status
Request parameters for verify SMS recovery Factor
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
passCode | OTP sent to device | Body | String | TRUE |
stateToken | state token for the current recovery transaction | Body | String | TRUE |
Response parameters for verify SMS recovery Factor
Recovery Transaction object with the current state for the recovery transaction
If the passCode
is invalid, you receive a 403 Forbidden
status code
with the following error:
Request example for verify SMS recovery Factor
Response example for verify SMS recovery Factor
Resend SMS recovery challengePOST /api/v1/authn/recovery/factors/sms/resend
Resends a SMS OTP (passCode
) to the user's mobile phone
Request parameters for resend SMS recovery challenge
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
stateToken | state token for the current recovery transaction | Body | String | TRUE |
Response parameters for resend SMS recovery challenge
Recovery Transaction object with the current state for the recovery transaction
Request example for resend SMS recovery challenge
Response example for resend SMS recovery challenge
Note: The
factorType
andrecoveryType
properties vary depending on recovery transaction.
Verify Call recovery Factor
POST /api/v1/authn/recovery/factors/call/verify
Verifies a Voice Call OTP (passCode
) sent to the user's device for primary authentication for a recovery transaction with RECOVERY_CHALLENGE
status
Request parameters for verify Call recovery Factor
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
passCode | Passcode received via the voice call | Body | String | TRUE |
stateToken | state token for the current recovery transaction | Body | String | TRUE |
Response parameters for verify Call recovery Factor
Recovery Transaction object with the current state for the recovery transaction
If the passCode
is invalid, you receive a 403 Forbidden
status code
with the following error:
Request example for verify Call recovery Factor
Response example for verify Call recovery Factor
Resend Call recovery challengePOST /api/v1/authn/recovery/factors/call/resend
Resends a Voice Call with OTP (passCode
) to the user's phone
Request parameters for resend Call recovery challenge
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
stateToken | state token for the current recovery transaction | Body | String | TRUE |
Response parameters for resend Call recovery challenge
Recovery Transaction object with the current state for the recovery transaction
Request example for resend Call recovery challenge
Response example for resend Call recovery challenge
The factorType
and recoveryType
properties vary depending on the recovery transaction.
Verify recovery token
POST /api/v1/authn/recovery/token
Validates a recovery token that was distributed to the end user to continue the recovery transaction
Request parameters for verify recovery token
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
recoveryToken | Recovery token that was distributed to the end user via out-of-band mechanism such as email | Body | String | TRUE |
options | Opt-in features for the authentication transaction | Body | Options object | FALSE |
Options object
You can modify the authentication transaction state machine through the following opt-in features:
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
multiOptionalFactorEnroll | Transitions transaction back to MFA_ENROLL state after successful Factor enrollment when additional optional factors are available for enrollment
| Boolean | TRUE | FALSE | FALSE |
Response parameters for verify recovery token
Recovery Transaction object with a RECOVERY
status and an issued stateToken
that must be used to complete the recovery transaction
You receive a 401 Unauthorized
status code if you attempt to use an expired or invalid
recovery token.
Request example for verify recovery token
Response example for verify recovery token
Answer recovery question
POST /api/v1/authn/recovery/answer
Answers the user's recovery question to ensure only the end user redeemed the
recovery token for recovery transaction with a RECOVERY
status
Request parameters for answer recovery question
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
answer | answer to user's recovery question | Body | String | TRUE |
stateToken | state token for the current transaction | Body | String | TRUE |
Response parameters for answer recovery question
Recovery Transaction object with the current state for the recovery transaction
You receive a 403 Forbidden
status code if the answer
to the user's
recovery question is invalid.
Request example for answer recovery question
Response example for answer recovery question
Reset password
POST /api/v1/authn/credentials/reset_password
Resets a user's password to complete a recovery transaction with a PASSWORD_RESET
state
This operation provides an option to revoke all the sessions of the specified user, except for the current session.
Request parameters for reset password
Parameter | Description | Param Type | DataType | Required | Default |
---|---|---|---|---|---|
newPassword | User's new password | Body | String | TRUE | |
stateToken | state token for the current transaction | Body | String | TRUE | |
revokeSessions | When set to true , revokes all user sessions, except for the current session
| Body | boolean | FALSE | FALSE |
Response parameters for reset password
Recovery Transaction object with the current state for the recovery transaction
You receive a 403 Forbidden
status code if the answer
to the user's
recovery question is invalid.
You will also receive a 403 Forbidden
status code if the newPassword
does not meet password policy requirements for the user.
Request example for reset password
Response example for reset password
State management operations
Get transaction state
POST /api/v1/authn
Retrieves the current transaction state for a state token
Request parameters for get transaction state
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
stateToken | state token for a transaction | Body | String | TRUE |
Response parameters for get transaction state
Transaction object with the current state for the authentication or recovery transaction
Request example for get transaction state
Response example for get transaction state
Previous transaction state
POST /api/v1/authn/previous
Moves the current transaction state back to the previous state. For example, when changing state from the start of primary authentication to MFA_ENROLL > ENROLL_ACTIVATE > OTP, the user's phone might stop working. Since the user can't see the QR code, the transaction must return to MFA_ENROLL.
Request parameters for previous transaction state
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
stateToken | state token for a transaction | Body | String | TRUE |
Response parameters for previous transaction state
Transaction object with the current state for the authentication or recovery transaction
Request example for previous transaction state
Response example for previous transaction state
Skip transaction state
POST /api/v1/authn/skip
Sends a skip link to skip the current transaction state and advance to the next state
If the response returns a skip link, then you can advance to the next state without completing the current state (such as changing the password). For example, after being warned that a password will soon expire, the user can skip the change password prompt by clicking a skip link.
Another example: a user has enrolled in multiple factors. After enrolling in one the user receives a skip link to skip the other factors.
Note: This operation is only available for
MFA_ENROLL
orPASSWORD_WARN
states when published as a link.
Request parameters for skip transaction state
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
stateToken | state token for a transaction | Body | String | TRUE |
Response parameters for skip transaction state
Transaction object with the current state for the authentication or recovery transaction
Request example for skip transaction state
Response example for skip transaction state
Cancel transaction
POST /api/v1/authn/cancel
Cancels the current transaction and revokes the state token
Request parameters for cancel transaction
Parameter | Description | Param Type | DataType | Required |
---|---|---|---|---|
stateToken | state token for a transaction | Body | String | TRUE |
Request example for cancel transaction
Transaction object
The Authentication API is a stateful API that implements a finite state machine with defined states and transitions. Each initial authentication or recovery request is issued a unique state token that must be passed with each subsequent request until the transaction is complete or canceled.
The Authentication API leverages the JSON HAL (opens new window) format to publish next
and prev
links for the current transaction state which should be used to transition the state machine.
Authentication transaction object
Property | Description | DataType | Nullable | Readonly | MaxLength |
---|---|---|---|---|---|
_embedded | embedded resources for the current status
| JSON HAL (opens new window) | TRUE | TRUE | |
_links | link relations for the current status
| JSON HAL (opens new window) | TRUE | TRUE | |
expiresAt | lifetime of the stateToken or sessionToken (See Tokens)
| Date | TRUE | TRUE | |
factorResult | optional status of last verification attempt for a given Factor | Factor Result | TRUE | TRUE | |
sessionToken | ephemeral one-time token used to bootstrap an Okta session | String | TRUE | TRUE | |
stateToken | ephemeral token that encodes the current state of an authentication transaction | String | TRUE | TRUE | |
status | current state of the authentication transaction | Transaction State | FALSE | TRUE | |
type Early Access | type of authentication transaction. Currently available during step-up authentication | Authentication Type | TRUE | TRUE |
Recovery transaction object
Property | Description | DataType | Nullable | Readonly | MaxLength |
---|---|---|---|---|---|
_embedded | embedded resources for the current status
| JSON HAL (opens new window) | TRUE | TRUE | |
_links | link relations for the current status
| JSON HAL (opens new window) | TRUE | TRUE | |
expiresAt | lifetime of the stateToken or recoveryToken (See Tokens)
| Date | TRUE | TRUE | |
factorResult | optional status of last verification attempt for the factorType
| Factor Result | TRUE | TRUE | |
factorType | type of selected Factor for the recovery transaction | EMAIL or SMS
| FALSE | TRUE | |
recoveryToken | ephemeral one-time token for recovery transaction to be distributed to the end user | String | TRUE | TRUE | |
recoveryType | type of recovery operation | PASSWORD or UNLOCK
| FALSE | TRUE | |
stateToken | ephemeral token that encodes the current state of a recovery transaction | String | TRUE | TRUE | |
status | current state of the recovery transaction | Transaction State | FALSE | TRUE |
Transaction state
An authentication or recovery transaction has one of the following states:
Value | Description | Next Action |
---|---|---|
LOCKED_OUT
| The user account is locked; self-service unlock or administrator unlock is required. | POST to the unlock link relation to perform a self-service unlock.
|
MFA_CHALLENGE
| The user must verify the Factor-specific challenge. | POST to the verify link relation to verify the Factor.
|
MFA_ENROLL_ACTIVATE
| The user must activate the Factor to complete enrollment. | POST to the next link relation to activate the Factor.
|
MFA_ENROLL
| The user must select and enroll an available Factor for additional verification. | POST to the enroll link relation for a specific Factor to enroll the Factor.
|
MFA_REQUIRED
| The user must provide additional verification with a previously enrolled Factor. | POST to the verify link relation for a specific Factor to provide additional verification.
|
PASSWORD_EXPIRED
| The user's password was successfully validated but is expired. | POST to the next link relation to change the user's expired password.
|
PASSWORD_RESET
| The user successfully answered their recovery question and must to set a new password. | POST to the next link relation to reset the user's password.
|
PASSWORD_WARN
| The user's password was successfully validated but is about to expire and should be changed. | POST to the next link relation to change the user's password.
|
RECOVERY_CHALLENGE
| The user must verify the Factor-specific recovery challenge. | POST to the verify link relation to verify the recovery Factor.
|
RECOVERY
| The user has requested a recovery token to reset their password or unlock their account. | POST to the next link relation to answer the user's recovery question.
|
SUCCESS
| The transaction completed successfully. | |
UNAUTHENTICATED Early Access
| User tried to access protected resource (for example: an app) but the user is not authenticated. | POST to the next link relation to authenticate user credentials.
|
You advance the authentication or recovery transaction to the next state by posting a request with a valid state token to the the next
link relation published in the JSON HAL links object for the response.
Enrolling a Factor and verifying a Factor do not have next
link relationships as the end user must make a selection of which Factor to enroll or verify.
Note: Never assume a specific state transition or URL when navigating the state object. Always inspect the response for
status
and dynamically follow the published link relations.
Authentication type
Early Access
Represents the type of authentication. Currently available only during SP-initiated step-up authentication and IDP-initiated step-up authentication.
Tokens
Authentication API operations return different token types depending on the state of the authentication or recovery transaction.
State token
Ephemeral token that encodes the current state of an authentication or recovery transaction.
- The
stateToken
must be passed with every request except when verifying arecoveryToken
that was distributed out-of-band - The
stateToken
is only intended to be used between the web application performing end-user authentication and the Okta API. It should never be distributed to the end user via email or other out-of-band mechanisms. - The lifetime of the
stateToken
uses a sliding scale expiration algorithm that extends with every request. Always inspect theexpiresAt
property for the transaction when making decisions based on lifetime.
Note: All Authentication API operations return
401 Unauthorized
status codes when you attempt to use an expired state token.
Note: State transitions are strictly enforced for state tokens. You receive a
403 Forbidden
status code if you call an Authentication API operation with astateToken
with an invalid state.
Recovery token
One-time token issued as recoveryToken
response parameter when a recovery transaction transitions to the RECOVERY
status.
- The token can be exchanged for a
stateToken
to recover a user's password or unlock their account. - Unlike the
statusToken
therecoveryToken
should be distributed out-of-band to a user such as via email. - The lifetime of the
recoveryToken
is managed by the organization's security policy.
The recoveryToken
is sent via an out-of-band channel to the end user's verified email address or SMS phone number and acts as primary authentication for the recovery transaction.
Note: Directly obtaining a
recoveryToken
is a highly privileged operation and should be restricted to trusted web applications. Anyone that obtains arecoveryToken
for a user and knows the answer to a user's recovery question can reset their password or unlock their account.
Session token
One-time token issued as sessionToken
response parameter when an authentication transaction completes with the SUCCESS
status.
- The token can be exchanged for a session with the Session API or converted to a session cookie.
- The lifetime of the
sessionToken
is 5 minutes.
Factor result
The MFA_CHALLENGE
or RECOVERY_CHALLENGE
state can return an additional property
factorResult that provides additional context for the last Factor verification attempt.
The following table shows the possible values for this property:
factorResult | Description |
---|---|
CANCELLED
| Factor verification was canceled by user |
ERROR
| Unexpected server error occurred verifying Factor. |
PASSCODE_REPLAYED
| Factor was previously verified within the same time window. User must wait another time window and retry with a new verification. |
TIMEOUT
| Unable to verify Factor within the allowed time window |
TIME_WINDOW_EXCEEDED
| Factor was successfully verified but outside of the computed time window. Another verification is required in current time window. |
WAITING
| Factor verification has started but not yet completed (e.g user hasn't answered phone call yet) |
Links object
Specifies link relations (see Web Linking (opens new window)) available for the current transaction state using the JSON (opens new window) specification. These links are used to transition the state machine of the authentication or recovery transaction.
The Links object is read-only.
Link Relation Type | Description |
---|---|
next | Transitions the state machine to the next state Note: The name of the link relationship provides a hint of the next operation required
|
prev | Transitions the state machine to the previous state |
cancel | Cancels the current transaction and revokes the state token |
skip | Skips over the current transaction state to the next valid state |
resend | Resends a challenge or OTP to a device |
Embedded resources
User object
A subset of user properties published in an authentication or recovery transaction after the user successfully completes primary authentication.
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
id | Unique key for user | String | FALSE | TRUE | TRUE |
passwordChanged | Timestamp when user's password last changed | Date | TRUE | FALSE | TRUE |
profile | User's profile | User Profile object | FALSE | FALSE | TRUE |
recovery_question | User's recovery question | Recovery Question object | TRUE | FALSE | TRUE |
User profile object
Subset of profile properties for a user
Property | Description | DataType | Nullable | Unique | Readonly | Validation |
---|---|---|---|---|---|---|
firstName | First name of user | String | FALSE | FALSE | TRUE | |
lastName | Last name of user | String | FALSE | FALSE | TRUE | |
locale | User's default location for purposes of localizing items such as currency, date time format, numerical representations, etc. | String | TRUE | FALSE | TRUE | RFC 5646 (opens new window) |
login | Unique login for user | String | FALSE | TRUE | TRUE | |
timeZone | User's time zone | String | TRUE | FALSE | TRUE | IANA Time Zone database format (opens new window) |
Remember device policy object
A subset of policy settings of the global session policy or an authentication policy published during MFA_REQUIRED
, MFA_CHALLENGE
states
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
allowRememberDevice | Indicates whether remember device is allowed based on the policy | Boolean | FALSE | FALSE | TRUE |
rememberDeviceByDefault | Indicates whether user previously opted to remember the current device | Boolean | FALSE | FALSE | TRUE |
rememberDeviceLifetimeInMinutes | Indicates how long the current verification would be valid (based on the policy) | Number | FALSE | FALSE | TRUE |
When sign-on policy is device based
When sign-on policy is time based
rememberDeviceByDefault
is true if the user has chosen to remember the current device.- The value of
rememberDeviceLifetimeInMinutes
depends on the Factor lifetime value configured in the Sign-On Policy rule.
When policy is not based on time or device
Recovery question object
User's recovery question used for verification of a recovery transaction
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
question | User's recovery question | String | FALSE | TRUE | TRUE |
Target object
Early Access
Represents the target resource that the user tried accessing. Typically this is the app that the user is trying to sign in to. Currently this is available only during SP-initiated step-up authentication and IDP-initiated step-up authentication.
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
_links | Discoverable resources for the target | JSON HAL (opens new window) | TRUE | FALSE | TRUE |
label | Label of the target resource | String | FALSE | FALSE | TRUE |
name | Name of the target resource | String | FALSE | FALSE | TRUE |
type | Type of the target resource. Currently only 'APP' is the supported type. | String | FALSE | TRUE | TRUE |
Authentication object
Early Access
Represents the authentication details that the target resource is using. Currently this is available only during SP-initiated step-up authentication and IDP-initiated step-up authentication.
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
issuer | The issuer of the assertion | Issuer object | FALSE | FALSE | TRUE |
protocol | The protocol of authentication | SAML2.0 , SAML1.1 or WS-FED
| FALSE | TRUE | TRUE |
Issuer object
The issuer that generates the assertion after the authentication finishes
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
id | Id of the issuer | String | TRUE | TRUE | TRUE |
name | Name of the issuer | String | FALSE | FALSE | TRUE |
uri | URI of the issuer | String | FALSE | FALSE | TRUE |
Password policy object
A subset of policy settings for the user's assigned password policy published during PASSWORD_WARN
, PASSWORD_EXPIRED
, or PASSWORD_RESET
states
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
complexity | Password complexity settings | Password Complexity object | FALSE | FALSE | TRUE |
expiration | Password expiration settings | Password Expiration object | TRUE | FALSE | TRUE |
Password expiration object
Specifies the password age requirements of the assigned password policy
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
passwordExpireDays | number of days before the password is expired | Number | FALSE | FALSE | TRUE |
Password complexity object
Specifies the password complexity requirements of the assigned password policy
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
excludeUsername | Prevents username or domain from appearing in the password | Boolean | FALSE | FALSE | TRUE |
minLength | Minimum number of characters for the password | Number | FALSE | FALSE | TRUE |
minLowerCase | Minimum number of lowercase characters for the password | Number | FALSE | FALSE | TRUE |
minNumber | Minimum number of numeric characters for the password | Number | FALSE | FALSE | TRUE |
minSymbol | Minimum number of symbol characters for the password | Number | FALSE | FALSE | TRUE |
minUpperCase | Minimum number of uppercase characters for the password | Number | FALSE | FALSE | TRUE |
Note: Duplicate the minimum Active Directory (AD) requirements in these settings for AD-sourced users. No enforcement is triggered by Okta settings for AD-sourced users.
Password age object
Specifies the password requirements related to password age and history
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
historyCount | Number of previous passwords that the current password can't match | Number | FALSE | FALSE | TRUE |
minAgeMinutes | Minimum number of minutes required since the last password change | Number | FALSE | FALSE | TRUE |
Factor object
A subset of
Factor properties published in an authentication transaction during MFA_ENROLL
, MFA_REQUIRED
, or MFA_CHALLENGE
states
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
_embedded | embedded resources related to the Factor | JSON HAL (opens new window) | TRUE | FALSE | TRUE |
_links | discoverable resources for the Factor | JSON HAL (opens new window) | TRUE | FALSE | TRUE |
factorType | type of Factor | Factor Type | FALSE | TRUE | TRUE |
id | unique key for Factor | String | TRUE | TRUE | TRUE |
profile | profile of a supported Factor | Factor Profile object | TRUE | FALSE | TRUE |
provider | Factor provider | Provider Type | FALSE | TRUE | TRUE |
vendorName | Factor Vendor Name (Same as provider but for On-Prem MFA it depends on Administrator Settings) | Provider Type | FALSE | TRUE | TRUE |
Factor embedded resources
TOTP Factor activation object
TOTP factors, when activated, have an embedded verification object that describes the TOTP (opens new window) algorithm parameters.
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
_links | Discoverable resources related to the activation | JSON HAL (opens new window) | TRUE | FALSE | TRUE |
encoding | Encoding of sharedSecret
| base32 or base64
| FALSE | FALSE | TRUE |
keyLength | Number of digits in a TOTP value | Number | FALSE | FALSE | TRUE |
sharedSecret | Unique secret key for prover | String | FALSE | FALSE | TRUE |
timeStep | Time-step size for TOTP | String | FALSE | FALSE | TRUE |
TOTP activation links objectNote: This object implements the TOTP standard (opens new window), which is used by apps like Okta Verify and Google Authenticator.
Specifies link relations (see Web Linking (opens new window)) available for the TOTP activation object using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and operations.
Link Relation Type | Description |
---|---|
qrcode | QR code that encodes the TOTP parameters that can be used for enrollment |
Phone object
Describes previously
enrolled phone numbers for the sms
Factor
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
id | Unique key for phone | String | FALSE | TRUE | TRUE |
profile | Profile of phone | Phone Profile object | FALSE | FALSE | TRUE |
status | Status of phone | ACTIVE or INACTIVE
| FALSE | FALSE | TRUE |
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
phoneNumber | Masked phone number | String | FALSE | FALSE | TRUE |
Push Factor activation object
Push factors must complete activation on the device by scanning the QR code or visiting the activation link sent via email or SMS.
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
_links | Discoverable resources related to the activation | JSON HAL (opens new window) | FALSE | FALSE | TRUE |
expiresAt | Lifetime of activation | Date | FALSE | FALSE | TRUE |
Specifies link relations (see Web Linking (opens new window)) available for the push Factor activation object using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and operations.
Link Relation Type | Description |
---|---|
qrcode | QR code that encodes the push activation code needed for enrollment on the device |
send | Sends an activation link via email or sms for users who can't scan the QR code
|
Factor links object
Specifies link relations (see Web Linking (opens new window)) available for the Factor using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and operations.
The Factor Links object is read-only.
Link Relation Type | Description |
---|---|
enroll | Enrolls a Factor |
questions | Lists all possible questions for the question Factor type
|
resend | Resends a challenge or OTP to a device |
verify | Verifies a Factor |