Flutter API Reference
Flutter API Reference
#Constructor
Configure and construct your Magic SDK instance.
#Arguments
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, rinkeby, kovan, or ropsten). |
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. |
#Example
01import 'package:magic_sdk/magic_sdk.dart';
02
03// Construct with an API key:
04Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
05
06// Construct with an API key and locale:
07Magic.instance = Magic("YOUR_PUBLISHABLE_KEY", locale: MagicLocale.en_US);
08
09// Construct with an
10Magic.instance = Magic.eth("YOUR_PUBLISHABLE_KEY", network: EthNetwork.rinkeby);
11
12Magic.instance = Magic.custom("YOUR_PUBLISHABLE_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.
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic magic = Magic.instance;
04
05magic.auth;
06magic.auth.loginWithMagicLink;
07magic.auth.loginWithSMS;
08magic.auth.loginWithEmailOTP;
#loginWithMagicLink
Authenticate a user passwordlessly using a "magic link" sent to the specified user's email address.
#Public Methods
Future<String> loginWithMagicLink({ required String email, bool showUI = true})
| Parameter | Type | Definition |
email | String | The user email to log in with. |
showUI | Boolean | If true, show an out-of-the-box pending UI while the request is in flight. |
#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
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
05// log in a user by using text input Controller
06try {
07 var magic = Magic.instance;
08 await magic.auth.loginWithMagicLink(email: textController.text);
09} catch {
10 // Handle errors if required!
11}
12
13// log in a user by their email, without showing an out-of-the box UI.
14try {
15 await m.auth.loginWithMagicLink({ email: 'hello@example.com', showUI: false });
16} catch {
17 // Handle errors if required!
18}
#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
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
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
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
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.
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
05var m = Magic.instance;
06
07m.user;
08m.user.getIdToken;
09m.user.generateIdToken;
10m.user.getMetadata;
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
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
05// Initiates the flow to update a user's current email to a new one.
06try {
07 var magic = Magic.instance;
08
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}
14
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;
21
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
#Example
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
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
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
05// Assumes a user is already logged in
06try {
07 var m = Magic.instance;
08
09 const idToken = await m.user.generateIdToken({ attachment: 'SERVER_SECRET' });
10} catch {
11 // Handle errors if required!
12}
#getMetadata
Retrieves information for the authenticated user.
#Arguments
None
#Returns
Future<UserMetadata>: 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. |
#Example
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
05// Assumes a user is already logged in
06try {
07 var m = Magic.instance
08 await m.user.getMetadata();
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
01import 'package:magic_sdk/magic_sdk.dart';
02
03Magic.instance = Magic("YOUR_PUBLISHABLE_KEY");
04
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
01import { Magic } from 'magic-sdk';
02
03const m = new Magic('API_KEY');
04
05try {
06 await m.user.logout();
07 debugPrint(await m.user.isLoggedIn()); // => `false`
08} catch {
09 // Handle errors if required!
10}
