Microsoft Entra ID
Authentication

Native authentication password reset API reference

In brief

The new reference documents recovery through email or SMS OTP, password updates, asynchronous polling, inline sign-in recovery, and token acquisition. It also lists configuration and permission prerequisites, including tenant and customer password reset enablement.

What Entra admins need to know

Administrators can review the prerequisites and enable password reset if their applications will use this flow; no mandatory action is stated.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

new file mode 100644

title: Native authentication password reset API reference description: Verify customer recovery credentials, update a password, poll completion, and acquire tokens with the Native Authentication API. author: adamstoffel ms.author: adamstoffel ms.service: identity-platform ms.subservice: external ms.topic: reference ms.custom: msecd-doc-authoring-1030 ms.date: 11/13/2026 ai-usage: ai-generated #customer intent: As an application developer, I want the password reset operations so that customers can recover access without bypassing authentication policies.

Native authentication password reset API reference

[!INCLUDE applies-to-external-only]

[!INCLUDE applies-to-authentication-native]

Password reset verifies a customer's recovery method, accepts a replacement password, and polls an asynchronous update. Email and SMS one-time passcode (OTP) methods support recovery. Multifactor authentication (MFA) and Conditional Access requirements can apply after the reset and before authorization completes.

For existing V1 integrations, use the V1 API reference.

Prerequisites

[!INCLUDE native-authentication-public-preview]

The examples use a tenant-verified custom-domain authority. custom_domain is the authentication domain and tenant is the tenant GUID.

Passwordless email-OTP accounts don't have a password to reset.

Start password reset

The diagram shows a standalone recovery sequence using email one-time passcode verification. Inline recovery instead uses the password method's recover link within the active sign-in transaction.

:::image type="complex" source="media/native-authentication-v2/native-password-reset-sequence.svg" alt-text="Sequence diagram of password recovery, passcode verification, password update, optional polling, and authorization-code exchange." lightbox="media/native-authentication-v2/native-password-reset-sequence.svg"::: The application starts authorization and follows the returned password-reset link with the customer's identifier and current token.

The application challenges an offered email recovery method, collects the delivered passcode, and verifies it. When requested, the user supplies a replacement password and the application follows the returned update link.

The application polls only while the current action is poll and completes any remaining authentication requirements. It then resumes authorization when allowed and exchanges the authorization code for tokens. :::image-end:::

Start authorization and follow the returned reset-password link (resetPassword or reset_password). Don't call sign-in discovery first:

POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
  "username": "[email protected]",
  "continuationToken": "******"
}

Send the customer's identifier in username and the current authorization token in continuationToken. The example uses an email address. A response can advertise an email recovery method:

{
  "state": "interactionRequired",
  "action": "challenge",
  "continuationToken": "******",
  "_links": {
    "self": {
      "href": "/{tenant}/api/v2.0/resetpassword/start"
    }
  },
  "_embedded": {
    "methods": [
      {
        "id": "{email_method_id}",
        "type": "email",
        "hint": "j****n@c****o",
        "_links": {
          "challenge": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
          },
          "verify": {
            "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
          }
        }
      }
    ]
  }
}

Select a returned email or SMS recovery method through user choice or application flow logic. The example shows email; for SMS, follow the returned SMS method's links without rewriting the example URL. Use the masked hint where the interface needs a destination label.

Inline recovery during sign-in

Offer inline recovery only when a password method in the current sign-in response advertises a recover link. Follow that link using the current sign-in continuation token. Don't start another authorization request or resubmit the username or password.

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

Both entry points use the recovery method, challenge, verification, password-update, and polling operations returned by the service.

Challenge and verify the recovery method

Post to the selected method's challenge link:

{
  "continuationToken": "******"
}

Use JSON and Accept: application/hal+json. The shared challenge operation returns the current method type, masked hint, codeLength, and verify and optional resend links.

Post the entered passcode to the returned verify link:

{
  "otp": "{one_time_passcode}",
  "continuationToken": "******"
}

Use the newest token for each request. For another code, use the current resend link and service limits, not an earlier challenge URL/token pair.

A successful verification can return the password method:

{
  "state": "interactionRequired",
  "action": "update",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "update": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
    }
  }
}

Use the password method ID from the returned update link, not the email or SMS recovery method ID. Inline recovery can retain the password method ID from the parent sign-in.

Update a password

Submit the replacement password with PUT, not POST:

PUT https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}
Content-Type: application/json
Accept: application/hal+json
{
  "newPassword": "{new_password}",
  "continuationToken": "******"
}
PropertyTypeRequiredDescription
continuationTokenString.Yes.Current token requesting password update.
newPasswordString.Yes.Replacement password. Password confirmation is local to your interface, not an additional request field.

The service can return:

{
  "state": "interactionRequired",
  "action": "poll",
  "pollInterval": "2",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "poll": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate"
    }
  }
}

This indicates an asynchronous update, not final authorization. Don't submit the password again while waiting or automatically repeat the update after an ambiguous network failure.

Poll password update

Follow the latest poll link:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

While the update is in progress, the service returns interactionRequired with action: poll, an updated token, and a poll link. Replace the prior response before the next poll.

When included, pollInterval is a string containing the interval in seconds. Use the current response's interval for the next request, and honor server retry guidance. The example "2" isn't a fixed service interval. Stop polling when the action changes or an error is returned, and handle any later authentication required by policy.

A continuation response is:

{
  "state": "continue",
  "continuationToken": "******",
  "_links": {
    "continue": {
      "href": "/{tenant}/oauth2/v2.0/authorize-challenge"
    }
  }
}

Complete policy requirements and acquire tokens

Password reset doesn't bypass MFA or Conditional Access. If another challenge is returned, complete it using the shared method operations. Token exchange follows completion of the remaining policy steps and authorization continuation.

After state: continue, resume authorization using the latest token and exchange the code. The requested scopes and claims remain those established at the beginning of the transaction.

Outcomes and errors

Use the shared error handling. The recovery contract describes these outcomes:

ConditionOutcome and client handling
Unknown usernameRecovery doesn't start. Use a generic customer-facing message.
Incorrect email or SMS passcodeHTTP 400 invalidGrant with innerError.code: invalidOneTimeCode. Let the user correct the code using the usable current state or an advertised resend.
Missing passcodeHTTP 400 invalidRequest. Correct the missing input.
ResendA new passcode is sent through the returned resend link.
Expired password-update tokenHTTP 400 expiredToken with innerError.code: expiredContinuationToken. Restart authorization.
Weak or common replacement passwordHTTP 400 invalidRequest with an applicable inner error such as passwordTooWeak or passwordTooCommon. Collect a compliant password.
Update in progressFollow the latest polling response and server retry guidance.
Poll fails password policyHTTP 400 invalidRequest with an inner error such as passwordTooCommon or passwordBannedByPolicy. Handle the error rather than polling indefinitely.
Account locked or disabled during pollingHTTP 403 forbidden with innerError.code: accountLocked. Stop the recovery operation.
Password update job failsHTTP 500 serverError. Show a clear failure without automatically repeating the password update.
Completed recoveryHandle any remaining policy actions, resume authorization, and request tokens.

This table describes specific outcomes, not an exhaustive error catalog. Password update acceptance, polling completion, and token issuance are separate boundaries.

Don't log recovery passcodes, replacement passwords, or transaction tokens. Record only safe diagnostic IDs, timestamps, and HTTP status. Don't automatically replay verification or password updates.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…