Hello @JenishaP.83116 (Customer)​ Thank you for posting on our Community page!

I understand how frustrating it can be when you’ve followed the documentation to the letter and the API still isn't behaving as expected. You’ve already tackled the two most common culprits by enabling Show lockout failures and disabling User enumeration prevention.

The reason you are still receiving a generic 401 Unauthorized on the API (and a generic "Unable to sign in" on the UI) comes down to how the Okta Authentication API handles state transitions.

The Missing Piece: Self-Service Account Unlock

The /api/v1/authn endpoint operates as a state machine. When it returns the LOCKED_OUT status, the JSON payload is designed to include a _links object containing the next step for the user—specifically, the unlock action.

If Self-Service Account Unlock is disabled in the user's password policy, or if the user hasn't enrolled in the required recovery authenticators, Okta has no "next step" to offer. Because the state machine cannot transition the user to a recovery flow, it drops the transaction entirely and falls back to a generic 401 Unauthorized error to prevent a dead-end API state.

How to Fix It To get the expected LOCKED_OUT API response and the correct UI prompt, you need to ensure the user is actually allowed to unlock their account:

1. Enable Self-Service Recovery:

• In the Okta Admin Console, navigate to Security > Authenticators.
  • On the Password row, select Actions > Edit.
  • Scroll down to the Rules section and edit the active rule that applies to your test user.
• Under the Account Recovery (or Recovery authenticators) section, ensure that you have selected at least one option under Users can initiate recovery with (e.g., Email, Phone).
  •  

1. Verify User Enrollment: * Ensure your test user is actually enrolled in the allowed recovery authenticator. If they haven't set up a recovery email or phone number, Okta cannot offer them the unlock flow, which will default back to a 401.
2. Check Okta ThreatInsight (Edge Case): * Ensure the IP address you are testing from isn't being blocked or rate-limited by Okta ThreatInsight or a strict Network Zone policy. If Okta detects suspicious behavior from an unknown device/IP during a lockout test, it can supersede standard policies and force a hard 401.

Once self-service recovery is permitted and accessible for that specific user, the /api/v1/authn endpoint will successfully return the LOCKED_OUT status along with the recovery links.

Thank you for reaching out to our Community and have a great day!

--

Help others in the community by liking or hitting Select as Best if this response helped you.

Hi Paul,

Thank you for your thorough answer. I am now able to initiate account recovery after adding a password rule allowing self-service account unlocking

For your last point, there is no rate-limiting or throttling. However, if there was, wouldn't the response be a 429, as documented in https://developer.okta.com/docs/reference/api/authn/#response-example-for-primary-authentication-with-a-public-application-and-show-lockout-failures ?