onSessionInvalidated

Function Signature

@discardableResult
public func onSessionInvalidated(
    _ listener: @escaping @MainActor () -> Void
) -> PortalSessionInvalidationHandle

Runs listener after the backend rejects this Portal’s credential (an HTTP 401 on a Portal-owned request, or an MPC AUTH_FAILED) and the SDK has invalidated it. Parameters

listener: Called at most once, on the main actor. This is your cue to clear local state and show the sign-in screen. It is retained until it runs or the credential is deallocated, so capture self weakly.

Returns

PortalSessionInvalidationHandle: Call cancel() to remove the listener. cancel() also suppresses a delivery that is already queued but has not run, and it is safe to call more than once or from inside the listener. The handle is not cancelled on deallocation, so you only need to keep it if you intend to unsubscribe. A Portal built from a Client API Key returns the shared PortalSessionInvalidationHandle.spent, and the listener never runs.

Notes

A late subscriber does not miss the event. Portal.init starts an authenticated request immediately. If the backend rejects it before you subscribe, the rejection is replayed: the listener still runs once, on the main actor.
Do not subscribe again on the same Portal from inside the listener. The instance is spent, and a new subscription would be called as well.
Fires at most once per credential, and never for a host-initiated clearSession().
The request that triggered the rejection still fails with its own error, and the listener runs in addition. Every later call on the Portal throws PortalCredentialError.sessionInvalidated, whose requiresReauthentication is true.
Only requests that carried the session to a Portal-owned host count: Portal’s own domains, or a host you configured on Portal, PortalConnect or PortalAuth. A 401 from a third-party RPC gateway or Google Drive, or a failed or cancelled passkey, does not invalidate the session.
The session is already invalidated when the listener runs, and its stored copy deleted. Do local cleanup, call auth.clearPersistedSession() so a re-delivered redirect cannot replay it, and do not call clearSession() again.
Available starting from SDK version 8.0.0.

Example Usage

import PortalSwift

func adopt(session: PortalSession) throws {
    let portal = try Portal(credentials: session)

    let handle = portal.onSessionInvalidated { [weak self] in
        guard let self else { return }
        Task {
            do {
                try await self.auth.clearPersistedSession()
            } catch {
                print("Error clearing the persisted session: \(error)")
            }
            self.portal = nil
            self.showSignIn()
        }
    }

    self.portal = portal
    self.sessionInvalidationHandle = handle   // call handle.cancel() to unsubscribe
}

Related Documentation

Getting Started

SDKs

APIs

Integrations

Resources

onSessionInvalidated