maxx_auth_sdk 0.1.0
maxx_auth_sdk: ^0.1.0 copied to clipboard
Official Flutter client for the MAXX Auth REST API.
MAXX Auth Flutter SDK #
Standalone Flutter client for the MAXX Auth v1 REST API. It does not depend on
the MAXX app, Firebase, or a private client secret. The public application ID
is sent as X-MAXX-Application-ID on every API request.
Add the package #
After publication, add this to your app's pubspec.yaml:
dependencies:
maxx_auth_sdk: ^0.1.0
For local development against this source tree, use path: ../maxx_auth_sdk
instead.
Run the interactive test app #
The package includes an example app at maxx_auth_sdk/example. From that
directory, run:
flutter pub get
flutter run -d chrome
In the app, configure the public application ID and deployed API URL, enter an email address you can access and a unique test password, then use Sign up. Enter the code delivered by email to confirm the address; then test sign-in, session validation, sign-out, and password reset. The example defaults to the MAXX Auth API deployment, but the ID and URL can be changed on screen. Do not use a production account password for testing.
Initialize #
Use the deployed API base URL from the MAXX Auth deployment. The documented
Cloud Functions URL has the form
https://asia-south2-<firebase-project-id>.cloudfunctions.net/maxxAuthApi.
Use HTTPS in production. Plain HTTP is accepted only for localhost emulator
testing. Never put a private credential in a Flutter application.
import 'package:maxx_auth_sdk/maxx_auth_sdk.dart';
await MaxxAuth.initialize(
applicationId: 'maxx_app_your_public_application_id',
baseUrl: 'https://asia-south2-your-project.cloudfunctions.net/maxxAuthApi',
);
final auth = MaxxAuth.instance;
Sign up, verify, sign in #
The API currently accepts only email and password at signup. Passwords
must be 12–128 characters. Signup sends an email verification code and does
not create a session.
final signup = await auth.signUp(
email: 'person@example.com',
password: 'a-long-unique-password',
);
if (signup.verificationRequired) {
// Ask the user for the code delivered by email.
await auth.confirmEmailVerification(token: verificationCode);
}
final session = await auth.signIn(
email: 'person@example.com',
password: 'a-long-unique-password',
);
print('Signed in as ${session.user.email}');
Current session and signout #
Sign-in session tokens are stored with flutter_secure_storage; passwords
are never persisted. getCurrentSession validates the stored token with the
server each time. An invalid session clears the stored token.
final session = await auth.getCurrentSession(); // null when signed out
await auth.signOut();
Verification and password reset #
await auth.requestEmailVerification(email: 'person@example.com');
await auth.confirmEmailVerification(token: verificationCode);
await auth.requestPasswordReset(email: 'person@example.com');
await auth.confirmPasswordReset(
token: resetCode,
password: 'a-new-long-unique-password',
);
The server returns a generic response for verification/reset requests whether
or not an eligible account exists. Password reset invalidates existing
sessions, so call getCurrentSession or sign in again afterward.
Errors and lifecycle #
API errors are surfaced as MaxxAuthException, with code, message, and
optional statusCode. Do not log passwords or session tokens. If you create a
client directly, call close() when it is no longer needed. The singleton
client can be reinitialized if an app changes its configuration.
The SDK implements the routes documented in the MAXX Auth API reference. The SDK package itself does not host or operate the API; applications require an active MAXX Auth integration and network access to the configured API URL.