> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PortalAuth

> Signs end users in directly with Portal and returns a session to initialize Portal with.

## Function Signature

```dart theme={null}
factory PortalAuth()
```

## Description

The entry point for [Client Auth](../guide/client-auth). `PortalAuth()` always returns the same instance, backed by a single native `PortalAuth`. Call [`configure`](./portalauthconfigure) once at startup, then start a sign-in, complete it from the redirect, and pass the resulting `PortalSession` to `Portal().initialize(session:)`.

`PortalAuth` never opens a browser and never listens for deep links: your app opens the authorize URL and passes every incoming link to [`handleRedirect`](./portalauthhandleredirect).

Available starting from `portal_flutter` 2.0.0.

## Methods

| Method | Description |
| - | - |
| [`configure`](./portalauthconfigure) | Sets the auth environment, redirect URL and sign-in options. |
| [`getMethods`](./portalauthgetmethods) | The sign-in methods enabled for the environment. |
| [`sendMagicLink`](./portalauthsendmagiclink) | Emails the user a magic link. |
| [`loginWithGoogle`](./portalauthloginwithgoogle) | A Google authorize URL for the app to open. |
| [`loginWithApple`](./portalauthloginwithapple) | An Apple authorize URL for the app to open. |
| [`handleRedirect`](./portalauthhandleredirect) | Completes a sign-in from the redirect URL. |
| [`verifyTotp`](./portalauthverifytotp) | Completes a sign-in that requires a TOTP code. |
| [`restoreSession`](./portalauthrestoresession) | The session persisted on this device, if any. |
| [`clearPersistedSession`](./portalauthclearpersistedsession) | Deletes the persisted session. |

## Types

### PortalSession

A signed-in session, passed to `Portal().initialize(session:)`. The session token stays on the native side; this is only a handle to it, valid for the lifetime of the app process. Apps never construct one.

| Property | Type | Description |
| - | - | - |
| `id` | `String` | Opaque native handle. Not a token: don't persist or parse it. |
| `endUserId` | `String` | The Portal end user this session belongs to. |

### PortalAuthResult

A sealed class returned by [`handleRedirect`](./portalauthhandleredirect), with two cases.

**`PortalAuthenticated`** — the sign-in completed, and the session is already persisted on the device.

| Property | Type | Description |
| - | - | - |
| `session` | `PortalSession` | The session to initialize `Portal` with. |
| `clientId` | `String?` | The user's Portal client ID. Only available at sign-in time; use `Portal().getClient()` afterwards. |
| `isAccountAbstracted` | `bool?` | Whether the user's client uses gas sponsorship. |

**`PortalTotpRequired`** — the environment requires a TOTP code before it issues a session. Complete it with [`verifyTotp`](./portalauthverifytotp).

| Property | Type | Description |
| - | - | - |
| `userJwt` | `String` | Short-lived credential for the verification step. |
| `totpLink` | `String?` | `otpauth://` enrollment URI on the user's first TOTP sign-in; `null` once they are enrolled. |
| `totpSecret` | `String?` | The base32 secret inside `totpLink`, for typing into an authenticator app. `null` when there is nothing to enroll. |
| `endUserId` | `String` | The Portal end user signing in. |

### PortalAuthMethods

Returned by [`getMethods`](./portalauthgetmethods).

| Property | Type | Description |
| - | - | - |
| `allowedAuthMethods` | `List<PortalAuthMethod>` | The enabled methods. Methods this SDK version doesn't recognize are dropped. |
| `autoCreateWallet` | `bool` | Whether the environment expects the app to create a wallet after sign-in. A hint only: neither the backend nor the SDK creates one. |

### PortalAuthMethod

An enum: `emailMagicLink`, `google`, `apple`.

### PortalAuthorizeUrl

Returned by [`loginWithGoogle`](./portalauthloginwithgoogle) and [`loginWithApple`](./portalauthloginwithapple).

| Property | Type | Description |
| - | - | - |
| `authorizeUrl` | `String` | The URL to open in a browser. Single-use: open it right away and never cache it. |

### PortalMagicLinkConfig

Passed to [`configure`](./portalauthconfigure) as `magicLink`.

| Property | Type | Description |
| - | - | - |
| `fromEmail` | `String` | The sender address. Must belong to a domain enabled for the auth environment. |
| `templateId` | `String` | The email template to send. Must exist for the auth environment. |

## Example

```dart theme={null}
import 'package:portal_flutter/portal_flutter.dart';

final auth = PortalAuth();

await auth.configure(
  authEnvironmentId: 'YOUR_AUTH_ENVIRONMENT_ID',
  redirectUrl: 'myapp://auth/callback',
);

final session = await auth.restoreSession();
if (session != null) {
  await Portal().initialize(session: session, rpcConfig: { /* ... */ });
}
```

## Errors

Every `PortalAuth` method throws a `PortalException` with an `AUTH_*` code. See [Handle errors](../guide/client-auth#handle-errors) for the full list.

## Related

* [Client Auth guide](../guide/client-auth)
* [clearSession](./clearsession)
* [onSessionInvalidated](./onsessioninvalidated)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.