Magical Auth Reference

To perform a Magical Auth 2FA verification you need to the following steps:

1. Initiate a 2FA verification session: This is done by sending a request from the user's device or from the backend by providing the user's phone number. The server will detect what verification channel the user is able to perform and initiate the verification process.
2. Verify the user: This is done by sending the verification code to the server to check if the user has successfully verified their phone number.

The Magical Auth service is available through the MagicalAuthClient through the GlideClient instance.

MagicAuthClient Reference

Methods

1. startServerAuth

Description: startServerAuth starts the 2FA verification process by sending a request from the application server by providing the user's phone number or email.

Syntax:

MagicAuthStartServerAuthResponse startServerAuth(BaseMagicAuthStartProps props) throws Exception

Parameters:

Property	Type	Description
phoneNumber	String	Optional - The phone number to verify
email	String	Optional - The email to verify
redirectUrl	String	Optional - URL to redirect after verification
state	String	Optional - A state value that can be used to maintain state between the client and server
otpConfirmationUrl	String	Optional - Custom URL for OTP confirmation page
rcsConfirmationUrl	String	Optional - Custom URL for RCS waiting page
fallbackChannel	String	Optional - Fallback verification method ('SMS', 'EMAIL', 'RCS', or 'NO_FALLBACK')

At least one of phoneNumber or email must be provided.

Returns:

• MagicAuthStartServerAuthResponse: An object containing the session identifier and the auth URL to redirect the user to complete the verification.

MagicAuthStartServerAuthResponse Properties:

Property	Type	Description
sessionId	String	Unique session identifier for this verification attempt
authUrl	String	URL where the user should be directed to complete verification

Example:

import com.glideapi.GlideClient;
import com.glideapi.magicauth.MagicAuthClient;

public class App {
    public static void main(String[] args) throws Exception {
        GlideClient glideClient = new GlideClient();
        
        // Start server auth with phone number
        MagicAuthClient.BaseMagicAuthStartProps props = new MagicAuthClient.BaseMagicAuthStartProps();
        props.phoneNumber = "+555123456789";
        MagicAuthClient.MagicAuthStartServerAuthResponse startResponse = glideClient.magicAuth.startServerAuth(props, null);
        
        System.out.println("Session ID: " + startResponse.sessionId);
        System.out.println("Auth URL: " + startResponse.authUrl);
    }
}

---

2. checkServerAuth

Description: checkServerAuth checks the status of a server-side verification initiated with startServerAuth.

Syntax:

CheckServerAuthResponse checkServerAuth(String sessionId) throws Exception

Parameters:

Property	Type	Description
sessionId	String	The session ID received from startServerAuth

Returns:

• CheckServerAuthResponse: An object containing the verification status.

CheckServerAuthResponse Properties:

Property	Type	Description
status	String	Current status of the verification ('PENDING' or 'COMPLETED')
verified	boolean	Whether the verification was successful (only meaningful when status is COMPLETED)

Example:

import com.glideapi.GlideClient;
import com.glideapi.magicauth.MagicAuthClient;

public class App {
    public static void main(String[] args) throws Exception {
        GlideClient glideClient = new GlideClient();
        
        // Check server auth status
        MagicAuthClient.MagicAuthCheckServerAuthResponse checkResponse = glideClient.magicAuth.checkServerAuth(
            "session-id-from-start-server-auth",
            null
        );
        
        if (checkResponse.status.equals("COMPLETED")) {
            if (checkResponse.verified) {
                System.out.println("Verification successful!");
            } else {
                System.out.println("Verification failed!");
            }
        } else {
            System.out.println("Verification still pending...");
        }
    }
}

---

3. startAuth

Description: startAuth starts the 2FA verification process by sending a request from the user's device or by providing the user's phone number.

Syntax:

MagicAuthStartResponse startAuth(BaseMagicAuthStartProps props, ApiConfig conf) throws Exception

Parameters:

Parameter	Type	Description
props	MagicAuthStartProps	An object containing the start auth properties.
conf	ApiConfig	An object containing optional API configuration like session.

MagicAuthStartProps Properties:

Property	Type	Description
phoneNumber	String	Optional - The phone number to verify.
email	String	Optional - The email to verify.
redirectUrl	String	Optional - The URL to which the user will be redirected after a successful verification.
state	String	Optional - A state value that can be used to maintain state between the client and server.
deviceIpAddress	String	Optional - The IP address of the user's device.
fallbackChannel	FallbackVerificationChannel	Optional - The fallback verification method.

One of phoneNumber or email must be provided.

deviceIpAddress should be provided when the request is made from a server on behalf of the end-user device, ensuring accurate IP-based verification and geolocation services.

Returns:

• MagicAuthStartResponse: An object containing the verification status.

MagicAuthStartResponse Properties:

Property	Type	Description
type	String	The value can be MAGIC, SMS or EMAIL
authUrl	String	Optional - The URL to open on the user's device in case of MAGIC type.
flatAuthUrl	String	Optional - The plain URL to use .In case you do not want to redirect or to open at user's device use this.
operatorId	String	Optional - The OperatorId.

Example:

import com.glideapi.GlideClient;
import com.glideapi.magicauth.MagicAuthClient;

public class App {
    public static void main(String[] args) throws Exception {
        GlideClient glideClient = new GlideClient();
        
        // Start auth with phone number
        MagicAuthClient.BaseMagicAuthStartProps props = new MagicAuthClient.BaseMagicAuthStartProps();
        props.phoneNumber = "+555123456789";
        MagicAuthClient.MagicAuthStartResponse startResponse = glideClient.magicAuth.startAuth(props, null);

        if (startResponse.type.equals("MAGIC")) {
            System.out.println("Open this URL on the user's device: " + startResponse.authUrl);
        } else {
            System.out.println("Verification code sent to the user's device using channel " + startResponse.type);
        }
    }
}

---

4. verifyAuth

Description: verifyAuth checks the code / token received from the user's device to verify the user.

Syntax:

MagicAuthCheckResponse verifyAuth(Object props, ApiConfig conf) throws Exception

Parameters:

Parameter	Type	Description
props	MagicAuthVerifyProps	An object containing the verification properties.
conf	ApiConfig	An object containing optional API configuration like session.

MagicAuthVerifyProps Properties:

Property	Type	Description
code	String	Optional - The code received from the user's device via EMAIL or SMS.
phoneNumber	String	Optional - The phone number to verify if SMS or MAGIC.
email	String	Optional - The email to verify in case of EMAIL
token	String	Optional - The token received from the user's device in case of MAGIC.
deviceIpAddress	String	Optional - The IP address of the user's device.

Two paramters need to be sent based on the type received from the startAuth method.

• SIM: token and phoneNumber
• MAGIC: token and phoneNumber
• SMS: code and phoneNumber
• EMAIL: code and email

Returns:

• MagicAuthCheckResponse: A MagicAuthCheckResponse instance.

MagicAuthCheckResponse Properties:

Property	Type	Description
verified	boolean	Whether the user is verified.

Example:

import com.glideapi.GlideClient;
import com.glideapi.magicauth.MagicAuthClient;

public class App {
    public static void main(String[] args) throws Exception {
        GlideClient glideClient = new GlideClient();

        // Create verification props
        MagicAuthClient.MagicAuthVerifyProps verifyProps = new MagicAuthClient.MagicAuthVerifyProps();
        verifyProps.phoneNumber = "+555123456789";
        verifyProps.token = "token-from-auth-response";
        MagicAuthClient.MagicAuthCheckResponse checkResponse = glideClient.magicAuth.verifyAuth(verifyProps, null);

        if (checkResponse.verified) {
            System.out.println("User verified");
        } else {
            System.out.println("User not verified");
        }
    }
}

---

Error Handling

Each method in ExampleService can throw errors under certain conditions. Developers should handle these exceptions as part of their implementation. Common errors include:

• InvalidInputError: Thrown when input parameters do not meet the required format or type.
• OperationFailedError: Thrown when an operation cannot be completed successfully due to various issues, such as network problems or service unavailability.

Type Definitions

ApiConfig

This object can be sent to most service apis to override the default configuration like the access token used in the request.

Properties

Property	Type	Description
session	Session	An optional session object for authentication and authorization.

Session

This object represents a user session with an access token, expiration time, and associated scopes.

Properties

Property	Type	Description
accessToken	String	The access token for authentication
expiresAt	long	Timestamp when the session expires
scopes	List<String>	List of authorization scopes