Introduction

What is Authyra?

Authyra is an authentication framework for Dart and Flutter. It manages the full auth lifecycle — sign-in, session persistence, token refresh, and multi-account state — without coupling to a backend, a navigation framework, or a UI library.

Unlike a BaaS SDK (Firebase Auth, Supabase Auth), Authyra doesn't talk to any external service. It orchestrates providers you configure and delegates storage to a backend you own.

Two packages

Authyra ships as two complementary packages:

Rule of thumb: depend on authyra_flutter for Flutter apps. Depend on authyra for Dart backends, unit tests, or any non-Flutter Dart target.

Core principles

1. Pure logic, no framework coupling

AuthyraClient is a plain Dart class — no BuildContext, no ChangeNotifier, no platform channel. The same code runs in a Flutter app, in a dart test suite, and in a Dart Frog handler.

2. Everything is an interface

AuthProvider and AuthStorage are abstract classes you implement:

• Any strategy — credentials, OAuth2, SAML, magic link, phone OTP — plugs in through the same interface.
• Any storage backend — flutter_secure_storage, Redis, SQLite, an in-memory map — is swappable.
• Tests replace providers and storage with three-line classes. No mocking framework needed.

3. Reactive by default

Every state change emits on authStateChanges: Stream<AuthState>. Wire it to StreamBuilder, Riverpod, Bloc, or a GoRouter redirect. AuthState uses Equatable, so identical consecutive states are deduplicated — no spurious rebuilds.

4. Synchronous state when you need it

AuthyraInstance (the singleton wrapper) maintains a synchronous cache:

Authyra.instance.currentUser        // AuthUser?   — no await
Authyra.instance.isAuthenticated    // bool        — no await
Authyra.instance.currentState       // AuthState   — no await

Safe to call in build() methods without FutureBuilder.

Package split — what lives where

Next steps

• Installation → — add the right package for your project
• Quick Start → — working sign-in in under 5 minutes
• Architecture → — how AuthyraClient, sessions, and providers fit together