Authentication

Introduction#

Magic provides a simple, frontend-focused authentication system with user caching and automatic token refresh. Like Laravel's Auth system, it's built around the concept of "guards" that define how users are authenticated.

Key Features#

Quick Start#

// 1. Register user factory (tells Magic how to create User from API data)
Auth.registerModel<User>(User.fromMap);

// 2. Login after API call
final response = await Http.post('/login', data: {
  'email': email,
  'password': password,
});

if (response.successful) {
  final user = User.fromMap(response['data']['user']);
  await Auth.login({
    'token': response['data']['token'],
  }, user);
  
  MagicRoute.to('/dashboard');
}

// 3. Check authentication anywhere
if (Auth.check()) {
  final user = Auth.user<User>();
  print('Welcome, ${user?.name}');
}

// 4. Logout
await Auth.logout();
MagicRoute.to('/login');

Configuration#

Create lib/config/auth.dart:

Map<String, dynamic> get authConfig => {
  'auth': {
    'defaults': {
      'guard': 'api',
    },
    'guards': {
      'api': {
        'driver': 'bearer',
      },
    },
    'endpoints': {
      'user': '/api/user',
    },
    'token': {
      'key': 'auth_token',
      'header': 'Authorization',
      'prefix': 'Bearer',
    },
    'auto_refresh': true,
  },
};

Register in your config and add AuthServiceProvider:

'providers': [
  (app) => AuthServiceProvider(app),
  // ...
],

The Auth Facade#

The Auth facade provides convenient access to authentication functionality:

// Check if user is authenticated
Auth.check()              // bool

// Check if user is a guest (not authenticated)
Auth.guest                // bool (a getter)

// Get the authenticated user
Auth.user<User>()         // User?

// Get user ID
Auth.id()                 // dynamic

// Login
await Auth.login(tokenData, user)

// Logout
await Auth.logout()

// Restore session from cache
await Auth.restore()

// Manually refresh token
await Auth.refreshToken()

// Token management
await Auth.hasToken()     // bool
await Auth.getToken()     // String?

// Resolve a guard by name (default guard when name is omitted)
Auth.guard()              // Guard
Auth.guard('api')         // Guard (named)

// Notifier that bumps on every auth state change
Auth.stateNotifier        // ValueNotifier<int>

Guards#

Guards define how users are authenticated. Each guard implements the Guard contract:

abstract class Guard {
  Future<void> login(Map<String, dynamic> data, Authenticatable user);
  Future<void> logout();
  bool check();
  bool get guest => !check();
  T? user<T extends Model>();
  dynamic id();
  void setUser(Authenticatable user);
  Future<bool> hasToken();
  Future<String?> getToken();
  Future<bool> refreshToken();
  Future<void> restore();

  /// Bumped on every auth state change (login, logout, restore).
  ValueNotifier<int> get stateNotifier;
}

Built-in Guards#

Custom Guards#

Create custom guards by extending BaseGuard:

class MyGuard extends BaseGuard {
  MyGuard() : super(
    userEndpoint: '/api/me',
    refreshEndpoint: '/api/refresh',
    refreshTokenKey: 'refresh_token',
    userFactory: (data) => User.fromMap(data),
  );

  @override
  Future<void> login(Map<String, dynamic> data, Authenticatable user) async {
    await startSession(
      user,
      token: data['token'] as String?,
      refreshToken: data['refresh_token'] as String?,
    );
  }
}

// Register the driver, then name it in a guard's `driver` config key
Auth.manager.extend('myguard', (config) => MyGuard());

startSession marks the session as opened and moves the in-memory token before its first await, then persists the tokens, sets the user and caches it. Prefer it to storeToken followed by setUser: both mark a new session, so a boot-time user sync or a refresh still in the air ignores its answer, and both delete a stored refresh token the new session does not carry, but only startSession also deletes the stored access token when the login carries none and leaves the user alone when a newer sign-in began during its writes.

Firebase Guard Example#

class FirebaseGuard extends BaseGuard {
  final _auth = firebase.FirebaseAuth.instance;

  FirebaseGuard() : super(userFactory: (data) => User.fromMap(data));

  @override
  Future<void> login(Map<String, dynamic> data, Authenticatable user) async {
    final idToken = await _auth.currentUser?.getIdToken();
    await startSession(user, token: idToken);
  }

  @override
  Future<void> restore() async {
    // Try cached user first (instant UI)
    final cached = await loadCachedUser();
    if (cached != null) setUser(cached);

    // Then verify with Firebase
    final fbUser = _auth.currentUser;
    if (fbUser == null) {
      await logout();
      return;
    }

    final user = userFactory!({
      'id': fbUser.uid,
      'email': fbUser.email,
      'name': fbUser.displayName,
    });
    await startSession(user, token: await fbUser.getIdToken());
  }

  @override
  Future<void> logout() async {
    await _auth.signOut();
    await super.logout();
  }
}

Reactive Auth State#

Every guard exposes a ValueNotifier<int> stateNotifier that increments on every auth state change (setUser(), logout(), and session restore). Use it to reactively rebuild UI without manual state management.

// Using ListenableBuilder (Flutter built-in)
ListenableBuilder(
  listenable: Auth.stateNotifier,
  builder: (context, _) {
    if (Auth.check()) {
      return Text('Hello, ${Auth.user<User>()?.name}');
    }
    return const Text('Not logged in');
  },
)

With MagicBuilder the pattern is identical; pass stateNotifier as the listenable:

MagicBuilder(
  listenable: Auth.stateNotifier,
  builder: (context, _) => Auth.check()
      ? const DashboardView()
      : const LoginView(),
)

setUser() is called internally by login(), restore(), and any custom guard that calls setUser(user) directly. Each call bumps stateNotifier.value by 1, triggering all registered listeners.

Auto Token Refresh#

AuthServiceProvider registers an AuthInterceptor on the network driver, which handles 401 responses:

1. Original request fails with 401, having presented the token
2. Interceptor calls Auth.refreshToken()
3. If refresh succeeds, original request is retried with new token
4. If refresh fails, user is logged out (unless the session changed meanwhile, see below)

BaseGuard.refreshToken() returns false unless the guard was built with both refreshEndpoint and refreshTokenKey. The built-in guards resolved from the auth config are built with neither, so for them step 4 follows any 401 on a presented credential. To refresh tokens, register a custom guard that passes both (see Custom Guards). The refresh posts {'refresh_token': ...} to refreshEndpoint and reads token or access_token (at the top level or under data) and an optional refresh_token from the response.

A 401 on a request that carried no auth header, or an older token, is ignored. The ladder above runs only when the refused request actually presented the header auth.token.header names, matched without regard to case, carrying the token the guard holds now. A request dispatched before a sign-in completed goes out anonymous, and its refusal arrives once the session exists; treating that as a rejection would end a session the server was never shown. Only a credential the server actually saw and refused ends a session.

A request that raced a token change is handed back refused, not replayed. When the refused request carried an older token and the guard already holds a newer one, the interceptor cannot tell a refresh from a different account signing in, and a replay with the newer token could answer one account's screen with another account's data. The caller receives the 401 and decides whether its request still stands.

A refresh belongs to the session it started in. When a sign-in, a sign-out or a restore of another account's token lands while a refresh is in the air, the refreshed token is discarded and the refused request is handed back with no retry and no logout, so the new session keeps its own token and stays signed in. A retry already on its way is sent with the refreshed token, never the new session's, and its answer is handed back as the 401. A sign-in without a token or a refresh_token deletes the stored one, so it never inherits the previous account's. storeToken counts as a sign-in too, and drops a stored refresh token it is not given; a custom guard that rotates its own token through it gets no retry and loses an in-flight boot sync, so rotate through refreshToken() with a refreshEndpoint instead.

A guard that does not extend BaseGuard keeps no token the interceptor can compare against, so it is judged on presence alone: a 401 ends its session only when the request carried the header auth.token.header names. A cookie-based guard, or one that sends its credential under another header, stays signed in while calls return 401; such a guard has to end its own session.

Auth.refreshToken() also returns false when the session changed while the refresh was in the air, so the example below signs out only when the stored token is still the one it refreshed. Comparing the stored token with the one that was refreshed does not detect a sign-in that stores the same token, so the example below can sign out a replacement session in that case. It can also sign out a sign-in that is still writing its tokens, because the second read can still find the previous token on disk. No public session-identity check is available.

// Manual token refresh
final refreshed = await Auth.getToken();
final success = await Auth.refreshToken();
if (!success && await Auth.getToken() == refreshed) {
  await Auth.logout();
  MagicRoute.to('/login');
}

Protecting Routes#

Core ships no auth middleware: write one that checks Auth.check(), register it in the Kernel under an alias (see Middleware), and name the alias on the route:

class EnsureAuthenticated extends MagicMiddleware {
  @override
  String? redirectTarget(String location) {
    if (!Auth.check() && location != '/login') return '/login';
    return null;
  }
}

Kernel.register('auth', () => EnsureAuthenticated());

// Single route
MagicRoute.page('/dashboard', () => DashboardView())
    .middleware(['auth']);

// Route group
MagicRoute.group(
  middleware: ['auth'],
  routes: () {
    MagicRoute.page('/dashboard', () => DashboardView());
    MagicRoute.page('/profile', () => ProfileView());
    MagicRoute.page('/settings', () => SettingsView());
  },
);

Write a guest middleware the same way to redirect authenticated users:

class RedirectIfAuthenticated extends MagicMiddleware {
  @override
  String? redirectTarget(String location) {
    if (Auth.check() && location != '/dashboard') return '/dashboard';
    return null;
  }
}

Login & Logout#

Login Flow#

class AuthController extends MagicController with ValidatesRequests {
  Future<void> login(Map<String, dynamic> data) async {
    clearErrors();
    
    final response = await Http.post('/login', data: data);
    
    if (response.successful) {
      final user = User.fromMap(response['data']['user']);
      
      await Auth.login({
        'token': response['data']['token'],
      }, user);
      
      Magic.success('Success', 'Welcome back!');
      MagicRoute.to('/dashboard');
    } else {
      handleApiError(response, fallback: 'Invalid credentials');
    }
  }
}

Logout Flow#

Future<void> logout() async {
  // Optionally notify backend
  await Http.post('/logout');
  
  // Clear local auth state
  await Auth.logout();
  
  Magic.snackbar('Logged Out', 'See you next time!');
  MagicRoute.to('/login');
}

Restoring Session on App Start#

AuthServiceProvider.boot() restores the session during Magic.init: when a user factory is registered (Auth.registerModel or Auth.manager.setUserFactory) and auto_refresh is not false, it calls Auth.restore(). Register the factory in a provider listed before AuthServiceProvider; a stored session with no factory is not restored and logs a warning.

With auto_refresh set to false the provider skips the restore, so call it yourself in main.dart:

void main() async {
  await Magic.init(...);
  
  // Restore auth session from cache
  await Auth.restore();
  
  runApp(MagicApplication(...));
}

A restore loads the cached user for a fast startup, then syncs with the API in the background.

A sign-in or a sign-out that completes while the sync is in the air wins: a late 401 about the restored token does not log out the new session, and a late 200 does not put the previous account back. A token refresh is not a new session, so a 200 that arrives under a refreshed token is still applied, and a 401 or 403 about a token that has since been refreshed is re-checked once under the current token, whose answer decides.

If userFactory is not set on the guard, the cache load and API sync steps are skipped gracefully (no error is thrown). Set userFactory via Auth.manager.setUserFactory() (or pass it to BaseGuard's constructor) during the boot phase to enable full session restore.

Auth Events#

BaseGuard (and FakeAuthManager's fake guard) dispatch MagicEvents through the Event facade; see Events for Event.listen<T>'s registration shape.

• AuthLogin fires at the end of startSession, once the token (when given) is persisted and the user is set and cached. Not fired on a restore; a restored user announces itself through AuthRestored instead. Skipped when the session ended or was replaced while the user was being cached, so a sign-out racing a sign-in never gets a stray AuthLogin for the session it just ended.
• AuthLogout fires from logout(), after the stateNotifier bump and before a rethrown Vault failure. It carries the user held when the logout began (null for a guest), and a guest logout still dispatches. It means "the in-memory session ended", not "the credentials are gone": it fires even when a Vault delete failed, so a listener releasing server-side state must still gate on Auth.hasToken().
• AuthRestored fires only after an API-confirmed sync (BaseGuard's background /user fetch inside restore()), never for the cache-only step that runs first. A sign-in or sign-out racing that sync suppresses it the same way AuthLogin is suppressed. Its changed field is false when the synced user serialises (toMap(), compared deeply) the same as the user the guard held before the sync, the usual warm cold boot, and true when an attribute moved or no user was held; a listener that remounts or refetches on it should skip changed: false. It defaults to true for an event built by hand.

class LogAuthEvents extends MagicListener<AuthLogout> {
  @override
  Future<void> handle(AuthLogout event) async {
    Log.info('Session ended for ${event.user?.authIdentifier ?? 'guest'}');
  }
}

Event.listen<AuthLogout>(() => LogAuthEvents());

Testing#

Replace the real auth manager with a FakeAuthManager using Auth.fake(). The fake routes all guard operations through an in-memory guard so tests run without platform channels or a real backend. Its login() and logout() dispatch AuthLogin/AuthLogout through the real Event facade too, same as the real guard, so a listener under test observes a faked session exactly as it would a real one.

import 'package:magic/testing.dart';

void main() {
  setUp(() {
    MagicApp.reset();
    Magic.flush();
  });

  tearDown(() => Auth.unfake());

  test('login sets authenticated state', () async {
    final fake = Auth.fake();

    await Auth.login({'token': 'abc'}, myUser);

    fake.assertLoggedIn();
    fake.assertLoginCount(1);
    expect(Auth.check(), isTrue);
    expect(Auth.user<User>(), same(myUser));
  });

  test('logout clears auth state', () async {
    final fake = Auth.fake(user: myUser);

    await Auth.logout();

    fake.assertLoggedOut();
  });
}

FakeAuthManager Assertions#

Call Auth.unfake() in tearDown() to restore normal auth resolution after each test.

Related Documentation#

• Authorization
• Vault
• Middleware
• HTTP Client
• Events