handle
The single completion path for every flow.
Returns null when the URL does not target this instance's redirectUrl or carries no Client Auth grant, so it is safe to call on every instance and safe for the app's router to try other handlers afterwards. Throws when the URL matches but carries ?error=….
Safe to call twice with the same grant, for as long as what it resolved to is still live: the first exchange's result is remembered and replayed, so a redirect the system re-delivers — an Intent that survives a rotation under launchMode="singleTask", say — resolves to the same AuthResult rather than failing the backend's single-use rejection. Nothing is re-exchanged and nothing is re-persisted on that path, and a replayed AuthResult.Authenticated carries the same PortalSession instance, so invalidating it reaches every copy.
A remembered session that has since been invalidated — by Portal.clearSession(), or by a 401 — is not replayed. A redirect re-delivered after a sign-out throws rather than resolving, and the app should treat it as it treats any other failed login.
Only a successful exchange is remembered, so a redirect that failed on a dropped connection stays retryable. What is remembered belongs to this instance and this process: it is dropped by clearPersistedSession, and after a process death the recovery is restoreSession rather than a replay.
On success the session is persisted before it is returned, so a Keystore write failure rejects the login rather than silently handing back a session that will not survive a restart.
URLs longer than 8192 characters return null without being parsed — a real redirect is far shorter, and this is the boundary where an unbounded inbound string first reaches the SDK.
Returns AuthResult.TotpRequired when the grant carries a userJwt instead of a session token. Nothing is persisted on that path; complete it with verifyTotp. A grant left on that step replays as the same step, so a redirect re-delivered mid-prompt resumes it; once verifyTotp accepts the code the same grant replays as the AuthResult.Authenticated it resolved to.
Throws
when the redirect reports an error.
when the exchange returns neither a session token nor a userJwt.
when the grant has already been spent — a redirect re-delivered after the session it produced was invalidated falls through to this.