API Reference

Exceptions

Complete reference for the AuthException hierarchy.

AuthException

Base class for every Authyra error.

class AuthException implements Exception {
  final String message;
  final String? code;
  final dynamic originalError;
  final StackTrace? stackTrace;
}

Catch this to handle any Authyra failure generically, or catch a specific subclass for targeted handling.

try {
  await Authyra.instance.signIn('email', params: CredentialsSignInParams(
    email: email, password: password,
  ));
} on AuthenticationFailedException {
  setState(() => _error = 'Invalid email or password.');
} on AuthException catch (e) {
  setState(() => _error = e.message);
}

Configuration

Exception	Thrown when
`NotInitializedException`	`Authyra.instance` (or `AuthyraClient` methods) is accessed before `initialize()` completes.
`InvalidConfigurationException`	Configuration is invalid, e.g. missing storage in `AuthyraClientBuilder`.

Provider

Exception	Thrown when
`ProviderNotFoundException`	`signIn(providerId, ...)` names an `id` not registered with the client.
`ProviderAlreadyRegisteredException`	Two providers share the same `id`, at construction or via `registerProvider`.
`InvalidProviderConfigException`	`registerProvider` is called with an empty `id`.

Authentication

Exception	Thrown when
`AuthenticationCancelledException`	The user cancels an interactive flow (closes the OAuth browser tab).
`AuthenticationFailedException`	The provider returned `null` (wrong credentials), an `AuthCallbacks` hook denied the operation, or an infrastructure error occurred. Carries an optional `providerName`.
`InvalidCredentialsException`	Credentials fail format validation before reaching the provider.
`MissingAuthParametersException`	Required sign-in params are missing.

Session & Token

Exception	Thrown when
`TokenExpiredException`	The active session's access token has expired and no refresh occurred (or `autoRefresh: false`).
`RefreshDeniedException`	A `RefreshProvider` signals a refresh that must not be retried: unsupported provider, no refresh token, or an `AuthCallbacks.onBeforeTokenRefresh` denial. `TokenRefresher` expires the session immediately instead of retrying.
`TokenRefreshFailedException`	A refresh attempt failed for a transient reason (network, server 5xx).
`InvalidTokenException`	A token is malformed or fails validation.
`SessionNotFoundException`	An operation requiring an active session finds none (e.g. `refreshSession()` with nobody signed in).
`SessionOperationException`	A session mutation (save, update, switch, remove) fails. Wraps the original error.

Storage

Exception	Thrown when
`StorageException`	The `AuthStorage` backend throws during `initialize()`, a read, or a write. Wraps the original error.

Network

Exception	Thrown when
`NetworkException`	A generic network failure occurs during a provider call.
`AuthTimeoutException`	An OAuth flow exceeds `OAuth2Config.timeout` (default 5 minutes).
`NoInternetException`	No network connectivity is detected (surfaced from a `SocketException`).

Validation

Exception	Thrown when
`ValidationException`	Base class for field-level validation failures.
`InvalidEmailException`	An email fails format validation.
`InvalidPasswordException`	A password fails policy validation.

Multi-account

Exception	Thrown when
`AccountNotFoundException`	`accounts.switchTo(userId)` or an internal registry lookup names an id with no registered session.
`DuplicateAccountException`	An operation would register an account that already exists.

Platform

Exception	Thrown when
`AuthPlatformException`	A platform channel call fails (wraps a native `PlatformException`).
`UnsupportedPlatformException`	A feature is invoked on a platform that doesn't support it.

Internal helper that normalises unexpected errors into the most specific AuthException subclass available (SocketException → NoInternetException, TimeoutException → AuthTimeoutException, PlatformException → AuthPlatformException, otherwise a generic AuthException). Already-typed AuthExceptions pass through unchanged. You won't call this directly; it's what wraps errors thrown from signIn/signOut/refreshSession.

Edit this pageorReport an issue

AuthState

Complete API reference for AuthState, the discriminated union emitted by authStateChanges.

Flutter App Example

A complete Flutter app with email/password and Google Sign-In using authyra_flutter.