Microsoft Entra ID
Authentication

Native authentication sign-in API reference

In brief

The new reference documents sign-in discovery, password and email/SMS OTP verification, policy-driven challenges, and authorization-code continuation for external applications. Existing V1 integrations are directed to the V1 API reference.

What Entra admins need to know

Administrators supporting external-tenant applications can use this guidance to coordinate application integrations with the documented sign-in flow. No administrator 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 sign-in API reference description: Discover sign-in methods, verify passwords and email passcodes, and handle policy-driven challenges 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 sign-in operations so that I can discover methods, verify credentials, and acquire tokens.

Native authentication sign-in API reference

[!INCLUDE applies-to-external-only]

[!INCLUDE applies-to-authentication-native]

Sign-in discovers the methods allowed for a customer's identifier and completes the required credential checks. Email-with-password and email one-time passcode (OTP) first-factor sign-in use the same response-driven model. The application selects allowed operations from the response through user choice or application flow logic, then satisfies the remaining authentication requirements before resuming authorization.

For existing V1 integrations, use the V1 API reference.

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

Start sign-in discovery

[!INCLUDE native-authentication-public-preview]

The diagram shows one possible sign-in sequence. Policy requirements can add, repeat, or reorder actions; always follow the current response.

:::image type="complex" source="media/native-authentication-v2/native-sign-in-sequence.svg" alt-text="Sequence diagram of native sign-in, credential verification, additional policy interactions, and authorization-code exchange." lightbox="media/native-authentication-v2/native-sign-in-sequence.svg"::: The application starts authorization, follows the returned sign-in link, and submits the user's identifier to discover available methods.

The application challenges an offered method and verifies the requested password or passcode. Email passcode delivery occurs when required. Additional policy interactions can require more verification or method registration.

Only when the current response permits continuation does the application resume authorization and exchange the resulting authorization code for tokens. :::image-end:::

Start authorization, then follow the returned sign_in link. Send the OAuth response's continuation_token value as continuationToken:

POST https://{custom_domain}/{tenant}/api/v2.0/signin/start
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "username": "[email protected]"
}
PropertyTypeRequiredDescription
continuationTokenString.Yes.Token from the current authorization challenge.
usernameString.Yes.Sign-in identifier accepted by tenant policy. This example uses email.

A password method-selection response can be:

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

Email-OTP sign-in returns an email method with its own id, masked hint, and allowed links. Your app can present returned choices or select an available method through application flow logic. Not every account offers both password and email OTP. Use generic discovery failures and protect account-existence information.

Challenge the selected method

Follow the method's challenge link with POST and the latest continuation token:

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

The shared challenge contract defines headers, response fields, and resend behavior.

Returned methodInteraction
passwordNo code is sent. Collect the password when the response requests verify.
emailCollect the delivered passcode. Use the returned masked hint and codeLength.
smsWhen advertised for a required factor, collect the SMS passcode using its own hint, length, and links.

Use resend only when the service advertises it and the customer requests another code. Don't resend automatically after a delivery delay.

Verify the credential

Follow the current verify link using POST. Use JSON, Accept: application/hal+json, and one of these bodies.

Password:

{
  "continuationToken": "******",
  "password": "******"
}

Email or SMS one-time passcode:

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

Use the credential field for the returned method type. Don't submit a password in otp or a passcode in password. Don't automatically replay verification after an ambiguous network failure.

Complete additional policy requirements

A successful verification can return another interactionRequired response with action: challenge and _embedded.methods. Select an advertised method and repeat challenge and verification with the new token and links.

Multifactor authentication (MFA) uses the same shared credential operations and supports email and SMS one-time passcodes as second factors. MFA through system policies is supported. Select a method from those returned for the required factor. The SMS example describes a second-factor interaction.

If the next response requires enroll or activate, use the inline registration contract. Email-with-password accounts can register an offered email or SMS factor. Email-OTP first-factor accounts can't reuse email as their second factor; use an offered alternative such as SMS.

If a required interaction isn't supported by your client, or the service returns state: redirect, stop native requests and offer a separately configured browser sign-in or a clear failure.

Resume authorization and acquire tokens

When policy requirements are satisfied, a response can return:

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

Post the token as form-encoded continuation_token to the returned link. Then exchange the authorization code for tokens. Neither a challenge response nor a successful verification response substitutes for that exchange.

Errors

Use the shared error envelope with these sign-in conditions:

ConditionStatus or errorHandling
Missing username or token400Correct the request.
Incorrect email or SMS passcode400 invalidGrant, with innerError.code: invalidOneTimeCodeLet the user correct the code using the usable current state or an advertised resend.
Missing passcode400 invalidRequestCorrect the missing input.
Invalid transaction state400 with the native error envelopeRestart instead of replaying an earlier token.
Throttling429Stop automatic retries and honor server guidance.
Unsupported native interactionstate: redirect, or OAuth invalid_grant with web_redirect_requiredStop native requests. A separate browser sign-in restarts authentication.

For other credential, discovery, or delivery failures, handle the actual status and stable error codes without exposing account-existence details. This table isn't an exhaustive error catalog. Preserve only safe request IDs, correlation IDs, timestamps, and status information, not credentials or whole response bodies.

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…