แก้ไข

Native authentication password reset API reference

Applies to: Green circle with a white check mark symbol that indicates the following content applies to external tenants. External tenants (learn more)

Authentication approach: Embedded native authentication.

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

Important

The Native Authentication API V2 is in preview. The Native Authentication API V1 remains generally available. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to preview features.

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.

Sequence diagram of password recovery, passcode verification, password update, optional polling, and authorization-code exchange.

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": "user@contoso.com",
  "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": "******"
}
Property Type Required Description
continuationToken String. Yes. Current token requesting password update.
newPassword String. 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:

Condition Outcome and client handling
Unknown username Recovery doesn't start. Use a generic customer-facing message.
Incorrect email or SMS passcode HTTP 400 invalidGrant with innerError.code: invalidOneTimeCode. Let the user correct the code using the usable current state or an advertised resend.
Missing passcode HTTP 400 invalidRequest. Correct the missing input.
Resend A new passcode is sent through the returned resend link.
Expired password-update token HTTP 400 expiredToken with innerError.code: expiredContinuationToken. Restart authorization.
Weak or common replacement password HTTP 400 invalidRequest with an applicable inner error such as passwordTooWeak or passwordTooCommon. Collect a compliant password.
Update in progress Follow the latest polling response and server retry guidance.
Poll fails password policy HTTP 400 invalidRequest with an inner error such as passwordTooCommon or passwordBannedByPolicy. Handle the error rather than polling indefinitely.
Account locked or disabled during polling HTTP 403 forbidden with innerError.code: accountLocked. Stop the recovery operation.
Password update job fails HTTP 500 serverError. Show a clear failure without automatically repeating the password update.
Completed recovery Handle 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.