feat(embedded): add /e/authorize email OTP flow by pmathew92 · Pull Request #1075 · auth0/Auth0.Android

pmathew92 · 2026-09-21T10:30:50Z

Summary

Adds EmbeddedAuthClient with the full multi-step embedded /e/authorize flow: authorize, identifyEmail, identifyPhone, challengeEmail, verifyOtp
Implements the continuation-as-error model — non-terminal steps complete through EmbeddedAuthException carrying a rotated auth_session and nextActions; verifyOtp is the terminal step that yields Credentials
Fixes scope omission: authorize() now accepts scope (default "openid profile email offline_access") and optional audience so the token exchange returns an id_token
Converts authorizeUrl to a lazy property to avoid recomputing the URL on every step

coderabbitai · 2026-09-21T10:30:56Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: b2040283-ffd0-4460-8a16-d14c91dc7e71

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

utkrishtsahu · 2026-09-28T09:11:17Z

 internal data class Alternative(
    @SerializedName("grant_type")
-    val grantType: String?,
+    val grantType: String,


Making grantType non-null looks risky. If the server sends an alternative without a grant_type, Gson will still shove null in here, and we end up building LoginOption.Unknown(rawGrantType = null) even though that field is non-null → NPE for consumers. We also lost the "just drop the entry" behavior (and its test). Can we keep String? and the null guard? Also this seems unrelated to the email-OTP feature.

grant_type is a required field as per the spec. If it returns null value , thats a deviation from what the server is supposed to send

utkrishtsahu · 2026-09-28T09:12:28Z

-        }
+        private const val DEFAULT_SCOPE = "openid profile email offline_access"
+
+        private val DEFAULT_CAPABILITIES: Set<EmbeddedCapability> =


Default capabilities include identify:phone, but identifyPhone is internal and there's no phone flow yet. So the server could hand back a phone step the app literally can't act on. Can we default to just the email-OTP actions for this milestone?

Removed phone for now

utkrishtsahu · 2026-09-28T09:12:59Z

+
+import com.auth0.android.embedded.EmbeddedAuthClient
+
+/** How a phone one-time code is delivered, chosen when calling [EmbeddedAuthClient.challengePhone]. */


This is public API for Flow 2, which isn't shipped yet — and the KDoc links to challengePhone, which doesn't exist. Once it's public we can't change it without a breaking release. Suggest keeping the phone/MFA types internal until that flow lands.

User can't use this till the next change lands. Keeping this class as it is for now shouldn'tbe a problem for the beta changes

Made this internal for now

utkrishtsahu · 2026-09-28T09:14:02Z

    private val clientId: String
        get() = auth0.clientId

+    private var transactionState: EmbeddedAuthState? = null


transactionState gets written on the network callback thread and read when the next step is built (possibly a different thread), with no @volatile or sync. That can leave us reading a stale/null session. At minimum @volatile; ideally a note that one client = one flow at a time.

Callbacks are usually returned on the main thread for us. But good to keep a safety check.

Added @volatile annotation to make this visible across threads

utkrishtsahu · 2026-09-28T09:14:51Z

+        override val capability: EmbeddedCapability = EmbeddedCapability.IDENTIFY_EMAIL
+    }
+
+    /** Continue by submitting a phone number. Act on it with [EmbeddedAuthClient.identifyPhone]. */


public type's KDoc points at identifyPhone, which is internal. (Goes away if we internalize the phone stuff.)

Removed the reference for now

utkrishtsahu · 2026-09-28T09:15:50Z

All the new tests use .execute() — the await() (coroutine) branches in StepRequest/AdvancingRequest aren't covered. runTest is already imported; could we add one continuation + one terminal await() case?

utkrishtsahu · 2026-09-28T09:16:45Z

-                }
-            }
-        }
+        private const val DEFAULT_SCOPE = "openid profile email offline_access"


Default scope requests offline_access (i.e. a refresh token by default), but the spec has scope as optional. Just confirming that's intended.

This is intended

utkrishtsahu · 2026-09-28T09:18:41Z

+        EmbeddedCapability.IDENTIFY_EMAIL -> NextAction.IdentifyEmail
+        EmbeddedCapability.IDENTIFY_PHONE -> NextAction.IdentifyPhone
+        EmbeddedCapability.CHALLENGE_EMAIL -> {
+            val index = (this[INDEX_KEY] as? Number)?.toInt() ?: return dropped(raw, INDEX_KEY)


If a required field is missing we drop the whole action — but if it was the only one, nextActions comes back empty and the user is stuck. Maybe surface it as Unknown instead so the menu still reflects what the server sent?

This is intended. Returning an Unknown in this scenario can cause confusion whne we have multiple item with the incorrect field.

utkrishtsahu · 2026-09-28T09:21:58Z

+            .toString()
+    }
+
+    private fun updateSessionFromFailure(error: EmbeddedAuthException) {


A network error wipes the session here. Network failures come through as unknown_error, not insufficient_authorization, so they hit the else and clear transactionState. But the spec (and our own authorize.md example) says network errors are safe to retry the same step — after this, the retry fails with no_active_session and forces a full restart. Can we only clear on terminal access_denied and keep the session on transient errors?

Yes. We can have check for transient errors for the same to ensure user is able to retry

Added the same

utkrishtsahu · 2026-09-28T09:22:49Z

+        audience: String? = null,
+        capabilities: Set<EmbeddedCapability> = DEFAULT_CAPABILITIES
+    ): Request<Void?, EmbeddedAuthException> {
+        transactionState = null


Session gets read/cleared at construction, not execution. authorize() nulls the session the moment you build the request, and the step methods snapshot it at build time too. So client.authorize(...) kills an in-progress flow even if you never start it. Safer to do this when the request actually runs.

Each authorize call is a start of a new login flow. So irrespective of it returns us a valid auth_session or not, we will clear the existing session to mark the termination of any ongoing flow

utkrishtsahu · 2026-09-28T09:26:07Z

StepRequest.kt and AdvancingRequest.kt forward addParameter(name, String) to the inner request but don't override the addParameter(name, Any) overload, so it hits the interface's no-op default and silently drops the param. FailedRequest overrides it — worth making these consistent.

NandanPrabhu · 2026-09-28T10:10:37Z

+ * to be usable.
 */
 internal fun Alternative.toLoginOption(): LoginOption? {
-    val grantType = grantType ?: return null


in which case now login option can be null since we made grantType as non optional

It can be null when other properties for a grant type return null when it is not expected to return null

NandanPrabhu · 2026-09-29T08:56:43Z

+            .addPathSegment(OAUTH_PATH)
+            .addPathSegment(TOKEN_PATH)
+            .build()
+        return factory.post(url.toString(), GsonAdapter(Credentials::class.java, gson))


@pmathew92 in exchange dont we need to add id token verification?

Good point. We can take it as a follow up separate PR and not club with this

pmathew92 changed the base branch from v5_development to SDK-11058 September 21, 2026 10:31

pmathew92 added this pull request to stack #1076 September 21, 2026 15:32

pmathew92 marked this pull request as ready for review September 22, 2026 04:45

pmathew92 requested a review from a team as a code owner September 22, 2026 04:45

pmathew92 changed the title ~~feat(embedded): add /e/authorize email OTP flow with sample app~~ feat(embedded): add /e/authorize email OTP flow Sep 22, 2026

pmathew92 force-pushed the feat/SDK-11336 branch from 51e714c to 1c6c787 Compare September 22, 2026 10:46

Base automatically changed from SDK-11058 to v5_development September 24, 2026 08:23

pmathew92 added 10 commits September 24, 2026 13:53

feat : Add support for /e/authorize email OTP flow

af824f7

Made connection mandatory request in the initial request

3138b09

Passing default scope to the initial authorize request

936c077

Minor change in the authorize url creation

25eb279

Added the UTs for authorize email OTP flow

4331096

Updated the sample app

dece9c1

Added examples.md file

1f9212a

Made index defaults to 0

a5bb721

Made the OtpChannel an enum type

ee600f5

Added few more helpers for the error cases

daf9967

pmathew92 force-pushed the feat/SDK-11336 branch from 36a65d6 to daf9967 Compare September 24, 2026 08:23

Addressed few chnages with respect to the updated spec

5e41d9a

NandanPrabhu reviewed Sep 25, 2026

View reviewed changes

Comment thread auth0/src/main/java/com/auth0/android/embedded/EmbeddedAuthClient.kt

pmathew92 added 4 commits September 28, 2026 08:44

Made indentify phone internal

a4f4fbf

Renamed EmbeddedAction to EmbeddedCApability

30d7efe

minor name change

1f40730

Removed client details

5041245

utkrishtsahu reviewed Sep 28, 2026

View reviewed changes

NandanPrabhu reviewed Sep 28, 2026

View reviewed changes

Comment thread auth0/src/main/java/com/auth0/android/embedded/authorize/StepRequest.kt

NandanPrabhu reviewed Sep 28, 2026

View reviewed changes

pmathew92 added 3 commits September 28, 2026 18:16

Addressed review feedbacks from @Utkrisht

2ad38f1

marked embedded authorize as beta

19d4179

removed phone reference in the sample

43e28d3

NandanPrabhu reviewed Sep 29, 2026

View reviewed changes

utkrishtsahu approved these changes Sep 29, 2026

View reviewed changes


		import com.auth0.android.embedded.EmbeddedAuthClient

		/** How a phone one-time code is delivered, chosen when calling [EmbeddedAuthClient.challengePhone]. */

Conversation

pmathew92 commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

coderabbitai Bot commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

utkrishtsahu commented Sep 28, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pmathew92 commented Sep 21, 2026 •

edited

Loading

coderabbitai Bot commented Sep 21, 2026 •

edited

Loading