Local Auth

https://pub.dev/documentation/local_auth/latest/
Admin
Local Auth is a Flutter plugin that provides on-device user authentication including biometric...
Tokens:7,488
Snippets:101
Trust Score:9.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### Get enrolled biometrics with getAvailableBiometrics

Source: https://pub.dev/packages/local_auth

Retrieves a list of enrolled biometric types. Use this to check if any biometrics are enrolled, and optionally check for specific types like strong or face. Be cautious when relying on specific types as they are device- and platform-specific.

```dart
final List<BiometricType> availableBiometrics = await auth.getAvailableBiometrics();

if (availableBiometrics.isNotEmpty) {
  // Some biometrics are enrolled.
}

if (availableBiometrics.contains(BiometricType.strong) ||
    availableBiometrics.contains(BiometricType.face)) {
  // Specific types of biometrics are available.
  // Use checks like this with caution!
}
```

--------------------------------

### LocalAuthException constructor

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthException-class.html

Creates a new LocalAuthException with the given code, optional description, and optional details.

```APIDOC
## LocalAuthException({required LocalAuthExceptionCode code, String? description, Object? details})

### Description
Creates a new exception with the given information.

### Parameters
- **code** (LocalAuthExceptionCode) - Required - The type of failure.
- **description** (String?) - Optional - A human-readable description of the failure.
- **details** (Object?) - Optional - Any additional details about the failure.

### Notes
- This constructor is const.
```

--------------------------------

### authenticate()

Source: https://pub.dev/documentation/local_auth/latest/index.html

Performs local authentication using biometrics or device credentials. Supports options for requiring biometrics, persisting across backgrounding, and customizing system dialog messages.

```APIDOC
## authenticate()

### Description
Performs local authentication on the device. By default, allows fallback to PIN, pattern, or passcode. Can be configured to require biometrics, persist across backgrounding, and customize system dialog messages.

### Method
Async method

### Parameters
#### Named Parameters
- **localizedReason** (String) - Required - The reason for authentication, shown to the user in the system dialog.
- **biometricOnly** (bool) - Optional - If true, requires biometric authentication and disables fallback to device credentials. Not supported on Windows.
- **persistAcrossBackgrounding** (bool) - Optional - If true, waits for the app to be foregrounded and retries authentication if canceled due to backgrounding.
- **authMessages** (List<AuthMessages>) - Optional - Platform-specific message customizations for system dialogs.

### Return Value
- **bool** - True if authentication succeeded, false otherwise.

### Exceptions
Throws **LocalAuthException** in most failure cases. See **LocalAuthExceptionCodes** for known error codes.

### Example
```dart
final bool didAuthenticate = await auth.authenticate(
  localizedReason: 'Please authenticate to show account balance',
  biometricOnly: true,
);
```
```

--------------------------------

### LocalAuthException.details

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthException-class.html

Any additional details about the failure.

```APIDOC
## Property: details

### Description
Any additional details about the failure.

### Type
Object?

### Attributes
- final
```

--------------------------------

### LocalAuthException.description

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthException-class.html

A human-readable description of the failure.

```APIDOC
## Property: description

### Description
A human-readable description of the failure.

### Type
String?

### Attributes
- final
```

--------------------------------

### LocalAuthentication()

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthentication-class.html

Constructs a new LocalAuthentication instance.

```APIDOC
## LocalAuthentication()

### Description
Creates a new instance of the LocalAuthentication class.

### Constructor
`LocalAuthentication()`

### Parameters
None.

### Returns
A new LocalAuthentication object.
```

--------------------------------

### Customize authentication dialogs with AuthMessages

Source: https://pub.dev/packages/local_auth

Customize the system dialog messages for Android and iOS by passing platform-specific AuthMessages. Requires importing the platform-specific implementation packages (local_auth_android and local_auth_darwin).

```dart
import 'package:local_auth_android/local_auth_android.dart';
import 'package:local_auth_darwin/local_auth_darwin.dart';

// ···
    final bool didAuthenticate = await auth.authenticate(
      localizedReason: 'Please authenticate to show account balance',
      authMessages: const <AuthMessages>[
        AndroidAuthMessages(
          signInTitle: 'Oops! Biometric authentication required!',
          cancelButton: 'No thanks',
        ),
        IOSAuthMessages(cancelButton: 'No thanks'),
      ],
    );
```

--------------------------------

### LocalAuthException Handling

Source: https://pub.dev/packages/local_auth

Handles exceptions thrown by `authenticate`. Use `LocalAuthExceptionCode` to check for specific error conditions like no biometric hardware or lockout.

```APIDOC
## LocalAuthException Handling

### Description
`authenticate` throws `LocalAuthException` in most failure cases. Use the `code` property to handle specific error conditions.

### Usage
```dart
try {
  final bool didAuthenticate = await auth.authenticate(
    localizedReason: 'Please authenticate to show account balance',
  );
  // ···
} on LocalAuthException catch (e) {
  if (e.code == LocalAuthExceptionCode.noBiometricHardware) {
    // Add handling of no hardware here.
  } else if (e.code == LocalAuthExceptionCode.temporaryLockout ||
      e.code == LocalAuthExceptionCode.biometricLockout) {
    // ...
  } else {
    // ...
  }
}
```

### Known Error Codes
- `LocalAuthExceptionCode.noBiometricHardware`
- `LocalAuthExceptionCode.temporaryLockout`
- `LocalAuthExceptionCode.biometricLockout`
```

--------------------------------

### isDeviceSupported()

Source: https://pub.dev/documentation/local_auth/latest/index.html

Checks if the device supports any form of local authentication (e.g., biometrics, PIN, pattern, or passcode). Returns a boolean indicating device-level authentication support.

```APIDOC
## isDeviceSupported()

### Description
Checks whether the device supports any form of local authentication, such as biometrics or device credentials. This is useful for determining if any device-level authentication is available.

### Method
Async method

### Return Value
- **bool** - True if the device supports local authentication, false otherwise.

### Example
```dart
final bool canAuthenticate = await auth.isDeviceSupported();
```
```

--------------------------------

### Handle LocalAuthException with error codes

Source: https://pub.dev/packages/local_auth

Wrap authenticate() in a try-catch to handle LocalAuthException failures. Check the error code against LocalAuthExceptionCode values like noBiometricHardware, temporaryLockout, and biometricLockout to provide specific handling.

```dart
import 'package:local_auth/local_auth.dart';
// ···
  final LocalAuthentication auth = LocalAuthentication();
  // ···
    try {
      final bool didAuthenticate = await auth.authenticate(
        localizedReason: 'Please authenticate to show account balance',
      );
      // ···
    } on LocalAuthException catch (e) {
      if (e.code == LocalAuthExceptionCode.noBiometricHardware) {
        // Add handling of no hardware here.
      } else if (e.code == LocalAuthExceptionCode.temporaryLockout ||
          e.code == LocalAuthExceptionCode.biometricLockout) {
        // ...
      } else {
        // ...
      }
    }
```

--------------------------------

### authenticate

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthentication-class.html

Authenticates the user with biometrics available on the device while also allowing the user to use device authentication - pin, pattern, passcode.

```APIDOC
## authenticate

### Description
Authenticates the user with biometrics available on the device while also allowing the user to use device authentication - pin, pattern, passcode.

### Method
`Future<bool> authenticate({required String localizedReason, Iterable<AuthMessages> authMessages = const <AuthMessages>[IOSAuthMessages(), AndroidAuthMessages(), WindowsAuthMessages()], bool biometricOnly = false, bool sensitiveTransaction = true, bool persistAcrossBackgrounding = false})`

### Parameters
- **localizedReason** (String) - Required - The reason for requesting authentication, shown to the user.
- **authMessages** (Iterable<AuthMessages>) - Optional - Custom messages for the authentication dialog. Defaults to platform-specific messages.
- **biometricOnly** (bool) - Optional - If true, only biometric authentication is allowed. Defaults to false.
- **sensitiveTransaction** (bool) - Optional - Indicates if the transaction is sensitive. Defaults to true.
- **persistAcrossBackgrounding** (bool) - Optional - If true, authentication persists across backgrounding. Defaults to false.

### Returns
`Future<bool>` - True if authentication succeeded, false otherwise.
```

--------------------------------

### LocalAuthException.toString()

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthException-class.html

Returns a string representation of this object.

```APIDOC
## Method: toString()

### Description
A string representation of this object.

### Returns
String

### Overrides
This method overrides the inherited toString() method.
```

--------------------------------

### Check device capabilities with canCheckBiometrics and isDeviceSupported

Source: https://pub.dev/packages/local_auth

Use this snippet to determine if local authentication is available on the device. It checks for biometric support and device-level authentication. The result can be used to conditionally show authentication UI.

```dart
import 'package:local_auth/local_auth.dart';
// ···
  final LocalAuthentication auth = LocalAuthentication();
  // ···
    final bool canAuthenticateWithBiometrics = await auth.canCheckBiometrics;
    final bool canAuthenticate = canAuthenticateWithBiometrics || await auth.isDeviceSupported();
```

--------------------------------

### LocalAuthException.code

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthException-class.html

The type of failure represented by this exception.

```APIDOC
## Property: code

### Description
The type of failure.

### Type
LocalAuthExceptionCode

### Attributes
- final
```

--------------------------------

### canCheckBiometrics and isDeviceSupported

Source: https://pub.dev/packages/local_auth

Checks if the device supports biometric authentication or any device-level authentication. Use canCheckBiometrics for biometrics support and isDeviceSupported for any local authentication.

```APIDOC
## canCheckBiometrics and isDeviceSupported

### Description
Checks whether local authentication is available on the device. `canCheckBiometrics` indicates biometric hardware support, while `isDeviceSupported()` indicates any device-level authentication support.

### Method
- `canCheckBiometrics` (property)
- `isDeviceSupported()` (method)

### Usage
```dart
import 'package:local_auth/local_auth.dart';
// ···
  final LocalAuthentication auth = LocalAuthentication();
  // ···
    final bool canAuthenticateWithBiometrics = await auth.canCheckBiometrics;
    final bool canAuthenticate = canAuthenticateWithBiometrics || await auth.isDeviceSupported();
```

### Returns
- `bool` - `true` if the respective capability is available.
```

--------------------------------

### isDeviceSupported

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthentication-class.html

Returns true if device is capable of checking biometrics or is able to fail over to device credentials.

```APIDOC
## isDeviceSupported

### Description
Returns true if device is capable of checking biometrics or is able to fail over to device credentials.

### Method
`Future<bool> isDeviceSupported()`

### Parameters
None.

### Returns
`Future<bool>` - True if the device supports biometrics or device credentials.
```

--------------------------------

### getAvailableBiometrics

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthentication-class.html

Returns a list of the biometrics that the app can currently use for authentication.

```APIDOC
## getAvailableBiometrics

### Description
Returns a list of the biometrics that the app can currently use for authentication.

### Method
`Future<List<BiometricType>> getAvailableBiometrics()`

### Parameters
None.

### Returns
`Future<List<BiometricType>>` - A list of available biometric types.
```

--------------------------------

### LocalAuthExceptionCode.values

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthExceptionCode.html

A constant list of all values in the LocalAuthExceptionCode enum, in order of their declaration. This can be used to iterate over all possible exception codes.

```APIDOC
## LocalAuthExceptionCode.values

### Description
A constant List of the values in this enum, in order of their declaration.

### Declaration
```dart
static const List<LocalAuthExceptionCode> values
```

### Return Value
- **List<LocalAuthExceptionCode>** - A constant list of all enum values.
```

--------------------------------

### Require biometric authentication with biometricOnly

Source: https://pub.dev/packages/local_auth

Authenticate using biometrics only, disallowing fallback to PIN, pattern, or passcode. Note that biometricOnly is not supported on Windows because the underlying API (Windows Hello) does not support selecting the authentication method.

```dart
final bool didAuthenticate = await auth.authenticate(
  localizedReason: 'Please authenticate to show account balance',
  biometricOnly: true,
);
```

--------------------------------

### stopAuthentication

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthentication-class.html

Cancels any in-progress authentication, returning true if auth was canceled successfully.

```APIDOC
## stopAuthentication

### Description
Cancels any in-progress authentication, returning true if auth was canceled successfully.

### Method
`Future<bool> stopAuthentication()`

### Parameters
None.

### Returns
`Future<bool>` - True if authentication was canceled successfully.
```

--------------------------------

### canCheckBiometrics

Source: https://pub.dev/documentation/local_auth/latest/local_auth/LocalAuthentication-class.html

Returns true if the device is capable of checking biometrics.

```APIDOC
## canCheckBiometrics

### Description
Returns true if the device is capable of checking biometrics.

### Property
`Future<bool> get canCheckBiometrics`

### Returns
`Future<bool>` - True if the device can check biometrics.
```

--------------------------------

### BiometricType enum values

Source: https://pub.dev/documentation/local_auth/latest/local_auth/BiometricType.html

The BiometricType enum defines constants for different biometric authentication types: face, fingerprint, iris, strong, and weak. Each value represents a specific biometric modality or classification.

```APIDOC
## BiometricType enum

### Description
Various types of biometric authentication. Some platforms report specific biometric types, while others report only classifications like strong and weak.

### Values
- **face** - Face authentication.
- **fingerprint** - Fingerprint authentication.
- **iris** - Iris authentication.
- **strong** - Any biometric (e.g., fingerprint, iris, or face) on the device that the platform API considers to be strong. For example, on Android this corresponds to Class 3.
- **weak** - Any biometric (e.g., fingerprint, iris, or face) on the device that the platform API considers to be weak. For example, on Android this corresponds to Class 2.

### Properties
- **hashCode** (int) - The hash code for this object. (inherited)
- **index** (int) - A numeric identifier for the enumerated value. (inherited)
- **name** (String) - The name of the enum value. (provided by EnumName extension)
- **runtimeType** (Type) - A representation of the runtime type of the object. (inherited)

### Methods
- **noSuchMethod**(Invocation invocation) → dynamic - Invoked when a nonexistent method or property is accessed. (inherited)
- **toString**() → String - A string representation of this object. (inherited)

### Operators
- **operator ==**(Object other) → bool - The equality operator. (inherited)

### Constants
- **values** → const List<BiometricType> - A constant List of the values in this enum, in order of their declaration.
```
Tokens:
Raw