PortalAuth

Class Definition

public final class PortalAuth

PortalAuth drives Portal’s Client Auth APIs and resolves a PortalSession that you pass to Portal(credentials:). It shares no state with Portal: it never touches wallets, MPC or signing, and your app owns all UI, redirect forwarding and wallet creation. Initializer

public convenience init(
    authEnvironmentId: String,
    redirectUrl: String,
    apiHost: String = "api.portalhq.io",
    magicLink: MagicLinkConfig? = nil,
    isAccountAbstracted: Bool? = nil
) throws

Parameters

authEnvironmentId: The Auth Environment ID from Authentication > Configure in the Portal dashboard. Sent as the x-portal-auth-environment-id header on every request, and used as the Keychain key for the persisted session, so two instances built with the same ID share one session.
redirectUrl: Where Portal sends the user once a magic link or provider sign-in completes. Must appear byte-for-byte on the environment’s Redirect URLs allow list and must match the URL scheme (or Universal Link) your app registers. signInWithGoogle / signInWithApple additionally require a custom scheme such as myapp://auth/callback.
apiHost: Optional Portal API host override. localhost and 127.0.0.1 use http://.
magicLink: The fromEmail and templateId that sendMagicLink requires. Omit it in an OAuth-only app.
isAccountAbstracted: Whether the client Portal creates for a first-time user uses gas sponsorship. Omitted from every request when nil. Only takes effect on a user’s first sign-in.

Throws

PortalAuthError.invalidArgument(name:): authEnvironmentId or redirectUrl is empty or blank. The initializer performs no network or Keychain I/O.

Properties and configuration

prefersEphemeralWebBrowserSession: Bool: When true, signInWith* opens a browser sheet that does not share Safari’s cookies, so an existing Google or Apple sign-in is not reused. Defaults to false. Set it to true to let a user who signed out pick a different account.
setAuthPresentationAnchor(_ anchor: ASPresentationAnchor): The window signInWith* presents the browser sheet from. Held weakly. Required before calling signInWithGoogle or signInWithApple.

Methods

Method	Purpose
`getMethods()`	Which sign-in methods the environment has enabled, plus the `autoCreateWallet` hint.
`sendMagicLink(_:)`	Email the user a sign-in link.
`loginWithGoogle()` / `loginWithApple()`	Fetch a provider authorize URL for you to open.
`signInWithGoogle()` / `signInWithApple()`	Complete a provider sign-in in an `ASWebAuthenticationSession` sheet.
`handleRedirect(_:)`	Exchange the grant on an inbound redirect URL for an `AuthResult`.
`verifyTotp(_:userJwt:)`	Submit a two-factor code.
`restoreSession()`	Rebuild the persisted session on launch.
`clearPersistedSession()`	Delete the persisted session.

Types

public struct MagicLinkConfig: Equatable {
    public let fromEmail: String
    public let templateId: String
}

public enum AuthMethod: String, Codable, CaseIterable {
    case emailMagicLink = "EMAIL_MAGIC_LINK"
    case google = "GOOGLE"
    case apple = "APPLE"
}

public struct AuthMethodsResult: Equatable {
    public let allowedAuthMethods: [AuthMethod]
    public let autoCreateWallet: Bool
}

public struct AuthorizeUrlResult: Equatable {
    public let authorizeUrl: String
}

public enum AuthResult: Sendable {
    case authenticated(AuthenticatedResult)
    case totpRequired(TotpRequiredResult)
}

public struct AuthenticatedResult: Sendable {
    public let session: PortalSession
    public let clientId: String?
    public let isAccountAbstracted: Bool?
}

public struct TotpRequiredResult: Equatable, Sendable {
    public let userJwt: String
    public let totpLink: String?
    public let endUserId: String
}

public protocol PortalSession: PortalCredentials {
    var endUserId: String { get }
}

PortalSession is a PortalCredentials: getToken() returns the Client Session Token until the session is invalidated, then throws PortalCredentialError.sessionInvalidated; invalidate() clears the in-memory token and deletes the persisted copy. endUserId is never secret and is the identifier to log and to key per-user state on. Errors PortalAuthError covers the authentication flow itself:

Case	When
`invalidArgument(name:)`	A required argument (`authEnvironmentId`, `redirectUrl`, `email`) was blank.
`magicLinkNotConfigured`	`sendMagicLink` was called on an instance built without `magicLink`.
`authMethodUnavailable(AuthMethod)`	A Google or Apple sign-in was started but the provider is not enabled for the environment.
`authenticationFailed(error:)`	The redirect carried an `error` parameter, for example `oauth_failed`.
`malformedResponse(path:missing:)`	A response did not carry the documented field.
`invalidGrantResponse`	The exchange returned neither a session token nor a `userJwt`.
`invalidUserJwt(detail:)`	The `userJwt` passed to `verifyTotp` could not be read.
`sessionStorageFailure(message:)`	The Keychain could not be read, written or deleted this time.
`accountAbstractionUnavailable(message:)`	`isAccountAbstracted: true` was requested but gas sponsorship is not enabled or configured.
`rateLimited`	The magic-link send limit for this address was hit (`429`).
`totpQrUnavailable`	A TOTP QR code could not be generated from `totpLink`.

PortalAuthSignInError is specific to signInWithGoogle / signInWithApple. Its raw values are the Web SDK’s popup codes: closed (POPUP_CLOSED), unavailable (POPUP_UNAVAILABLE), signInInProgress (SIGN_IN_ALREADY_IN_PROGRESS) and callbackIncomplete (CALLBACK_INCOMPLETE). Transport failures are not remapped. A 401 from any PortalAuth call surfaces as PortalRequestsError.unauthorized, unchanged; see Handle errors for what it means on each call. Notes

Hold one long-lived instance. handleRedirect remembers the last grant it exchanged so a redirect delivered twice resolves to the same result; that memory lives on the instance.
The persisted session is stored in the Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, keyed by authEnvironmentId, in a namespace separate from wallet shares. It never syncs through iCloud Keychain, and it survives app deletion.
Available starting from SDK version 8.0.0.

Example Usage

import PortalSwift

do {
    let auth = try PortalAuth(
        authEnvironmentId: "YOUR_AUTH_ENVIRONMENT_ID",
        redirectUrl: "myapp://auth/callback",
        magicLink: MagicLinkConfig(
            fromEmail: "hello@auth.example.com",
            templateId: "YOUR_TEMPLATE_ID"
        )
    )

    let methods = try await auth.getMethods()
    print("Enabled methods: \(methods.allowedAuthMethods.map(\.rawValue))")
} catch PortalAuthError.invalidArgument(let name) {
    print("Missing configuration value: \(name)")
} catch {
    print("Error creating PortalAuth: \(error)")
}

Related Documentation

Getting Started

SDKs

APIs

Integrations

Resources