Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.magic.link/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

​
Getting Started

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

​
Performance improvement (optional)

We use service workers for for better performance on web3 operations. If you’d like to take advantage of this performance boost, you’d have to enable app bound domains. To do that, add the following to your Info.plist and rebuild your app:
plist
<key>WKAppBoundDomains</key>
<array>
  <string>https://auth.magic.link</string>
</array>

​
Constructor

Magic()
ParameterTypeDefinition
apiKeyStringYour publishable API Key retrieved from the Magic Dashboard.
network?EthNetwork | CustomNodeConfiguration(EthNetwork): A representation of the connected Ethereum network (.mainnet or .goerli).

⁠(CustomNodeConfiguration): A custom Ethereum Node configuration with the following shape:

rpcUrl (String): A URL pointing to your custom Ethereum Node.

⁠chainId? (Number): 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.
locale?LocaleCustomize the language of Magic’s modal, email and confirmation screen. See Localization for more.

​
Initialization

In AppDelegate
Swift
import MagicSDK
import UIKit

@UIApplicationMain
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // assign the newly created Magic instance to shared property
    // Test key defaults to "goerli", live key defaults to "mainnet"
    Magic.shared = Magic(apiKey: "PUBLISHABLE_API_KEY")
    // Construct with an API key and options:
    Magic.shared = Magic(apiKey: "PUBLISHABLE_API_KEY", ethNetwork: .goerli)
    // Construct with an API key and custom node options:
    let customNode = CustomNodeConfiguration(rpcUrl: "https://polgyon-rpc.com", chainId: 137)
    Magic.shared = Magic(apiKey: "PUBLISHABLE_API_KEY", customNode: customNode)
    // Construct with an API key and custom locale
    Magic.shared = Magic(apiKey: "PUBLISHABLE_API_KEY", locale: "es")

    return true
}

​
Auth Module

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

​
loginWithSMS

Authenticate a user passwordlessly using a one-time code sent to the specified phone number. List of Currently Blocked Country Codes Arguments
  • configuration (LoginWithSMSConfiguration):
    • phoneNumber (string): The user phone number to log in with
    • showUI (boolean): If true, show an out-of-the-box pending UI while the request is in flight
Returns
  • Promise<string | null>: The promise resolves upon authentication request success and rejects with a specific error code if the request fails. The resolved value is a Decentralized ID token with a default 15-minute lifespan.
Example Closure
Swift
import MagicSDK

class LoginViewController: UIViewController {
    @IBOutlet weak var phoneNumberInput: UITextField!
    let magic = Magic.shared

    @IBAction func login() {
        guard let magic = magic else { return }
        guard let phoneNumber = self.phoneNumberInput.text else { return }

        let configuration = LoginWithSMSConfiguration(phoneNumber: phoneNumber, showUI: true)

        magic.auth.loginWithSMS(configuration, response: { response in
            guard let token = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", token)
        })
    }
}
Promise
Swift
import MagicSDK

class LoginViewController: UIViewController {
    @IBOutlet weak var phoneNumberInput: UITextField!
    let magic = Magic.shared

    @IBAction func login() {
        guard let magic = magic else { return }

        let configuration = LoginWithSMSConfiguration(phoneNumber: phoneNumber)

        magic.auth.loginWithSMS(configuration).done({ result in
            print(result) // DIDToken
        }).catch({
            print(error) // handle Error
        })
    }
}

​
loginWithEmailOTP

Authenticate a user passwordlessly using an email one-time code sent to the specified user’s email address. Arguments
  • configuration (LoginWithEmailOTPConfiguration):
    • email (string): The user email to log in with
Returns
  • Promise<string | null>: The promise resolves upon authentication request success and rejects with a specific error code if the request fails. The resolved value is a Decentralized ID token with a default 15-minute lifespan.
Example Closure
Swift
import MagicSDK

class LoginViewController: UIViewController {
    @IBOutlet weak var emailInput: UITextField!
    let magic = Magic.shared

    @IBAction func login() {
        guard let magic = magic else { return }
        guard let email = self.emailInput.text else { return }

        let configuration = LoginWithEmailOTPConfiguration(email: email)

        magic.auth.loginWithEmailOTP(configuration, response: { response in
            guard let token = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", token)
        })
    }
}
Promise
Swift
import MagicSDK

class LoginViewController: UIViewController {
    @IBOutlet weak var emailInput: UITextField!
    let magic = Magic.shared

    @IBAction func login() {
        guard let magic = magic else { return }

        let configuration = LoginWithEmailOTPConfiguration(email: self.emailInput.text!)

        magic.auth.loginWithEmailOTP(configuration).done({ result in
            print(result) // DIDToken
        }).catch({
            print(error) // handle Error
        })
    }
}

​
Wallet Module

The Wallet Module and its members are accessible on the Magic SDK instance by the wallet property.

​
connectWithUI

Renders a simple login form UI to collect the user’s email address and authenticate them passwordlessly using a one-time passcode (OTP) sent to their email address they input. Arguments
  • None
Returns
  • A promiEvent which returns an String[] when resolved: An array of user accounts that are connected, with the first element being the current public address of the user. You can read more on PromiEvents here.
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func logout() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        magic.wallet.connectWithUI(response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }
}

​
showUI

Displays the fully navigable wallet to the user that adheres to the toggled configurations on your developer dashboard’s Widget UI tab. ⁠ ⁠This is only supported for users who login with email or Google. User must be signed in for this method to return or else it will throw an error. Arguments
  • None
Returns
  • Promise which resolves when the user closes the window
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func logout() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        magic.wallet.showUI(response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }
}

​
User Module

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

​
updateEmail

Initiates the update email flow that allows a user to change to a new email. Arguments
  • configuration (UpdateEmailConfiguration):
    • email (string): The user email to update with
    • showUI (boolean): If true, show an out-of-the-box pending UI while the request is in flight
Returns
  • Promise<Bool>: The promise resolves with a true boolean value if update email is successful and rejects with a specific error code if the request fails
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {

    let magic = Magic.shared

    // Initiates the flow to update a user's current email to a new one.
    func updateEmail() {

        guard let magic = magic else { return }

        // Assuming user is logged in
        let configuration = UpdateEmailConfiguration(email: "[email protected]", showUI: true)
        magic.user.updateEmail(configuration, response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }

}

​
getIdToken

Generates a Decentralized Id Token which acts as a proof of authentication to resource servers. Arguments
  • configuration (GetIdTokenConfiguration):
    • lifespan (number): will set the lifespan of the generated token. Defaults to 900s (15 mins).
Returns
  • Promise<String>: Base64-encoded string representation of a JSON tuple representing [proof, claim]
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {

    let magic = Magic.shared

    func getIdToken() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        let configuration = GetIdTokenConfiguration(lifespan: 900)

        magic.user.getIdToken(configuration, response: { response in
            guard let token = response.result
                else { return print(response.error.debugDescription) }
            print(token)
        })
    }

}

​
generateIdToken

Generates a Decentralized Id Token with optional serialized data. Arguments
  • configuration (GenerateIdTokenConfiguration):
    • lifespan (number): will set the lifespan of the generated token. Defaults to 900s (15 mins).
    • attachment (str): will set a signature of serialized data in the generated token. Defaults to "none".
Returns
  • Promise<String>: Base64-encoded string representation of a JSON tuple representing [proof, claim]
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func generateIdToken() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        let configuration = GenerateIdTokenConfiguration(lifespan: 900, attachment: "none")

        magic.user.generateIdToken(configuration, response: { response in
            guard let token = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", token)
        })
    }
}

​
getInfo

Retrieves information for the authenticated user. Arguments
  • None
Returns
  • Promise<UserInfo> - The issuer, email and cryptographic public address of the authenticated user.
    • 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
    • phoneNumber (string): Phone number 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 (RecoveryFactor):
      • value (string): Recovery value such as phone number
      • type (RecoveryMethodType): The method used for account recovery
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func getInfo() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        magic.user.getInfo(response: { response in
            guard let metadata = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", metadata)
        })
    }
}

​
isLoggedIn

Checks if a user is currently logged in to the Magic SDK. Arguments
  • None
Returns
  • Promise<Bool>: A boolean value indicating if a user is logged in
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func isLoggedIn() {
        guard let magic = magic else { return }

        magic.user.isLoggedIn(response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }
}

​
logout

Logs out the currently authenticated Magic user. Arguments
  • None
Returns
  • Promise<Bool>: A boolean value indicating if a user has been logged out
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func logout() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        magic.user.logout(response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }
}

​
showSettings

Displays an iframe with the current user’s settings. Allows for users to update their email address, enable multi-factor authentication, and add a recovery factor.
Access to MFA and account recovery require paid add-ons.
Arguments
  • None
Returns
  • Promise which resolves when the user closes the window
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func logout() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        magic.user.showSettings(response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }
}

​
updatePhoneNumber

Initiates the update phone number flow that allows a user to change their phone number. Arguments
  • configuration:
    • phoneNumber (str): The user phone number to update with
Returns
  • PromiEvent<boolean>: The promise resolves with a true boolean value if update email is successful and rejects with a specific error code if the request fails
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func logout() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        let configuration = (phoneNumber: phoneNumber)
        magic.user.updatePhoneNumber(configuration, response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }
}

​
recoverAccount

Initiates the account recovery flow that allows a user to recover their account using their email address. Arguments
  • configuration (RecoverAccountConfiguration):
    • email (str): The user email address to recover account with
Returns
  • PromiEvent<boolean>: The promise resolves with a true boolean value if the account recovery is successful and rejects with a specific error code if the request fails
Example
Swift
import MagicSDK

class MagicViewController: UIViewController {
    let magic = Magic.shared

    func logout() {
        guard let magic = magic else { return }

        // Assuming user is logged in
        let configuration = RecoverAccountConfiguration(email: "[email protected]")
        magic.user.recoverAccount(configuration, response: { response in
            guard let result = response.result
                else { return print("Error:", response.error.debugDescription) }
            print("Result", result)
        })
    }
}

​
Error Handling

There are three types of error class to be aware of when working with Magic’s iOS SDK:

​
Provider

Swift
public enum ProviderError: Swift.Error {
  // The provider is not configured with an authDelegate
  case encodingFailed(Swift.Error?)
  // Decoding the JSON-RPC request failed
  case decodingFailed(json: String)
  // Convert string failed
  case invalidJsonResponse(json: String)
  // Missing callback
  case missingPayloadCallback(json: String)
}

​
Network

Swift
public enum Error: Swift.Error {
  /// The response did not include expected results
  case unexpectedResponse(Swift.Error?)
  /// The server returned an unexpected response code
  case invalidResponseCode
}

​
Events

Swift
enum Error: Swift.Error{
  case eventCallbackMissing
}

​
Resources