Flutter API Reference

#Overview

The Magic SDK for Flutter is your entry-point to secure, passwordless authentication for your mobile app. This guide will cover some important topics for getting started with Flutter APIs and to make the most of Magic's features.

#Getting Started

The Magic class is the entry-point to the Magic SDK. It must be instantiated with a Magic publishable key.

#Installation

Add magic_sdk to your pubspec.yaml:

Yaml

01dependencies:

02  flutter:

03    sdk: flutter

04  magic_sdk: ^6.0.1

Run the following command to install dependencies:

Bash

01$ dart pub get

#Performance improvement (optional)

We use service workers for for better performance on web3 operations. They are enabled by default on Android, but if you'd like to take advantage of this performance boost on iOS as well, you'd have to enable app bound domains. To do that, add the following to your Info.plist and rebuild your app:

01<key>WKAppBoundDomains</key>

02<array>

03  <string>https://auth.magic.link</string>

04</array>

#Constructor

#`Magic()`

Magic(apiKey, {MagicLocale locale})

Parameter	Type	Definition
`apiKey`	String	Your publishable API Key retrieved from the Magic Dashboard.
`locale?`	MagicLocale	Customize the language of Magic's modal, email and confirmation screen. See Localization for more.

Magic.eth(String apiKey, { required EthNetwork network, MagicLocale locale})

Parameter	Type	Definition
`network`	EthNetwork	A representation of the connected Ethereum network (one of: mainnet or goerli).

Magic.custom(String apiKey, { required String rpcUrl, int? chainId, MagicLocale locale})

Parameter	Type	Definition
`rpcUrl`	String	A URL pointing to your custom Ethereum Node.
`chainId?`	int	Some Node infrastructures require you to pass an explicit chain ID. If you are aware that your Node requires this configuration, pass it here as an integer.

#Initialization

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03// Construct with an API key:

04Magic.instance = Magic("PUBLISHABLE_API_KEY");

06// Construct with an API key and locale:

07Magic.instance = Magic("PUBLISHABLE_API_KEY", locale: MagicLocale.en_US);

09// Construct with an API key and network:

10Magic.instance = Magic.eth("PUBLISHABLE_API_KEY", network: EthNetwork.goerli);

12// Construct with an API key and custom node options:

13Magic.instance = Magic.custom("PUBLISHABLE_API_KEY", rpcUrl: "https://your.custom.url/", chainId: 1);

#Auth Module

The Auth Module and its members are accessible on the Magic SDK instance by the auth property.

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic magic = Magic.instance;

05magic.auth;

06magic.auth.loginWithSMS;

07magic.auth.loginWithEmailOTP;

#`loginWithSMS`

Authenticate a user passwordlessly using a one-time code sent to the specified phone number.

List of Currently Blocked Country Codes

#Public Methods

Future<String> loginWithSMS({ required String email })

Parameter	Type	Definition
`phoneNumber`	String	The phone number to log in with.

#Returns

Future<string> The future resolves upon authentication request success and throws with a specific error code if the request fails. The resolved value is a Decentralized ID token with a default 15-minute lifespan.

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05// log in a user by using text input Controller

06try {

07  var magic = Magic.instance;

08  await magic.auth.loginWithSMS(phoneNumber: textController.text);

09} catch {

10  // Handle errors if required!

11}

#`loginWithEmailOTP`

Authenticate a user passwordlessly using an email one-time code sent to the specified user's email address.

#Public Methods

Future<String> loginWithEmailOTP({ required String email })

Parameter	Type	Definition
`email`	String	The user email to log in with.

#Returns

Future<string> The future resolves upon authentication request success and throws with a specific error code if the request fails. The resolved value is a Decentralized ID token with a default 15-minute lifespan.

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05// log in a user by using text input Controller

06try {

07  var magic = Magic.instance;

08  await magic.auth.loginWithEmailOTP(email: textController.text);

09} catch {

10  // Handle errors if required!

11}

#User Module

The User Module and it's members are accessible on the Magic SDK instance by the user property.

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05var m = Magic.instance;

07m.user;

08m.user.getIdToken;

09m.user.generateIdToken;

10m.user.getInfo;

11m.user.isLoggedIn;

12m.user.updateEmail;

13m.user.logout;

#`updateEmail`

Initiates the update email flow that allows a user to change their email address.

#Arguments

Future<bool> updateEmail({required String email, bool showUI = true})

Parameter	Type	Definition
`email`	String	The new email to update to.
`showUI?`	Boolean	If `true`, shows an out-of-the-box pending UI which includes instructions on which step of the confirmation process the user is on. Dismisses automatically when the process is complete.

#Returns

Future<boolean>: The future resolves with a true boolean value if update email is successful and rejects with a specific error code if the request fails

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05// Initiates the flow to update a user's current email to a new one.

06try {

07  var magic = Magic.instance;

09  /* Assuming user is logged in */

10  await magic.user.updateEmail(email: 'new_user_email@example.com');

11} catch {

12  // Handle errors if required!

13}

15/**

16 * Initiates the flow to update a user's current email to a new one,

17 * without showing an out-of-the box UI.

18 */

19try {

20  var magic = Magic.instance;

22  /* Assuming user is logged in */

23  await magic.user.updateEmail({ email: 'new_user_email@example.com', showUI: false });

24} catch {

25  // Handle errors if required!

26}

#`getIdToken`

Generates a Decentralized Id Token which acts as a proof of authentication to resource servers.

#Arguments

Future<String> getIdToken({int lifespan = 900})

Parameter	Type	Definition
`lifespan?`	int	Will set the lifespan of the generated token. Defaults to 900s (15 mins)

#Returns

Future<string>: Base64-encoded string representation of a JSON tuple representing [proof, claim]

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05// Assumes a user is already logged in

06try {

07  var m = Magic.instance;

08  const idToken = await m.user.getIdToken();

09} catch {

10  // Handle errors if required!

11}

#`generateIdToken`

Generates a Decentralized Id Token with optional serialized data.

#Arguments

Future<String> generateIdToken({int lifespan = 900, String attachment = 'none'})

Parameter	Type	Definition
`lifespan?`	int	Will set the lifespan of the generated token. Defaults to 900s (15 mins)
`attachment?`	String	Will set a signature of serialized data in the generated token. Defaults to `"none"`

#Returns

Future<string>: Base64-encoded string representation of a JSON tuple representing [proof, claim]

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05// Assumes a user is already logged in

06try {

07  var m = Magic.instance;

09  const idToken = await m.user.generateIdToken({ attachment: 'SERVER_SECRET' });

10} catch {

11  // Handle errors if required!

12}

#`getInfo`

Retrieves information for the authenticated user.

#Arguments

None

#Returns

Future<UserInfo>: an object containing the issuer, email and cryptographic public address of the authenticated user

Value	Type	Definition
`issuer`	String	The Decentralized ID of the user. In server-side use-cases, we recommend this value to be used as the user ID in your own tables.
`email`	String	Email address of the authenticated user.
`publicAddress`	String	The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
`isMfaEnabled`	Boolean	A boolean indicating if user has multi-factor authentication enabled.
`recoveryFactors`	`List<RecoveryFactor>` `value` `type`

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05// Assumes a user is already logged in

06try {

07  var m = Magic.instance

08  await m.user.getInfo();

09} catch {

10  // Handle errors if required!

11}

#`isLoggedIn`

Checks if a user is currently logged in to the Magic SDK.

#Arguments

None

#Returns

Future<Boolean>

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

03Magic.instance = Magic("PUBLISHABLE_API_KEY");

05try {

06  const isLoggedIn = await m.user.isLoggedIn();

07  debugPrint(isLoggedIn); // => `true` or `false`

08} catch {

09  // Handle errors if required!

10}

#`logout`

Logs out the currently authenticated Magic user

#Arguments

None

#Returns

Future<Boolean>

#Example

Dart

01import { Magic } from 'magic-sdk';

03const m = new Magic('PUBLISHABLE_API_KEY');

05try {

06  await m.user.logout();

07  debugPrint(await m.user.isLoggedIn()); // => `false`

08} catch {

09  // Handle errors if required!

10}

#OAuth Module

The OAuth Module and it's members are accessible on the Magic SDK instance by the oauth property.

Dart

01import 'package:magic_sdk/magic_sdk.dart';

02import 'package:magic_ext_oauth/magic_ext_oauth.dart';

04Magic magic = Magic.instance;

06magic.oauth;

07magic.oauth.loginWithPopup;

#`loginWithPopup`

Starts the OAuth 2.0 login flow.

note

Only available with Dedicated Wallet.

#Arguments

provider (String): The OAuth provider being used for login
redirectURI (String): A URL a user is sent to after they successfully log in
scope? (Array): Defines the specific permissions an application requests from a user

#Returns

None

#Valid Providers

Name	Argument
Google	`'google'`
Facebook	`'facebook'`
Twitter	`'twitter'`
Apple	`'apple'`
Discord	`'discord'`
GitHub	`'github'`
LinkedIn	`'linkedin'`
Bitbucket	`'bitbucket'`
GitLab	`'gitlab'`
Twitch	`'twitch'`
Microsoft	`'microsoft'`

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

02import 'package:magic_ext_oauth/magic_ext_oauth.dart';

04Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");

05Magic magic = Magic.instance;

07var configuration = OAuthConfiguration(provider: OAuthProvider.GITHUB, redirectURI: 'YOUR_APP_SCHEME://');

08var result = await magic.oauth.loginWithPopup(configuration);

#OpenID Module

note

This module requires an enterprise agreement. For more details click here.

The OpenID Module and it's members are accessible on the Magic Flutter SDK instance by the openid property.

To use the OpenID Module in your application, install magic-ext/oidc along with magic-sdk.

Dart

01# pubspec.yaml

02dependencies:

03  flutter:

04    sdk: flutter

05  magic_sdk: ^5.0.1

06  magic_ext_oidc: ^0.0.1

08magic.openid;

09magic.openid.loginWithOIDC;

#`loginWithOIDC`

Authenticate users via your preferred OIDC client.

note

Only available with Dedicated Wallet.

#Arguments

jwt (String): The OIDC token from your identity provider
providerId (String): An alphanumeric ID provided by Magic after successful configuration of your identity provider

#Returns

String: The resolved value is a Decentralized ID token with a default 15-minute lifespan

#Example

Dart

01import 'package:magic_sdk/magic_sdk.dart';

02import 'package:magic_ext_oidc/magic_ext_oidc.dart';

04void main() {

05  Magic.instance = Magic("PUBLISHABLE_API_KEY");

07  // Use the OIDC extension to perform login

08  var configuration = OpenIdConfiguration(

09       jwt: 'JWT_FROM_YOUR_OPEN_ID_PROVIDER',

10⁠       providerId:'YOUR_MAGIC_PROVIDER_ID');

11⁠

12  var didToken = await magic.openid.loginWithOIDC(configuration);

14  // Use the DID token for further authentication or requests

15  print('DID Token: $didToken');

16}

Flutter API Reference

Flutter API Reference

iOS API Reference

Unity API reference

About

Developers

Resources

Social

About

Developers

Resources

Social

About

Developers

Resources

Social