Magical Auth Reference
To perform a Magical Auth 2FA verification you need to the following steps:
- 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.
- 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. 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:
startAuth(props: MagicAuthStartProps = {}, conf: ApiConfig = {}): Promise<MagicAuthStartResponse>;
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. |
One of phoneNumber
or email
must be provided.
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. |
Example:
import { GlideClient } from "glide-sdk";
async function main() {
const glide = new GlideClient();
const magicAuthStartResponse = await glide.magicAuth.startAuth({
phoneNumber: "+555123456789"
});
if (magicAuthStartResponse.type === "MAGIC") {
console.log(`Open this URL on the user's device: ${magicAuthStartResponse.authUrl}`);
} else {
console.log(`Verification code sent to the user's device using channel ${magicAuthStartResponse.type}`);
}
}
main().catch(console.error);
2. verifyAuth
Description:
verifyAuth
checks the code / token received from the user's device to verify the user.
Syntax:
verifyAuth(props: MagicAuthVerifyProps, conf: ApiConfig): Promise<MagicAuthCheckResponse>;
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. |
Two paramters need to be sent based on the type
received from the startAuth
method.
- SIM:
token
andphoneNumber
- MAGIC:
token
andphoneNumber
- SMS:
code
andphoneNumber
- EMAIL:
code
andemail
Returns:
MagicAuthCheckResponse
: AMagicAuthCheckResponse
instance.
MagicAuthCheckResponse Properties:
Property | Type | Description |
---|---|---|
verified | boolean | Whether the user is verified. |
Example:
import { GlideClient } from "glide-sdk";
async function main() {
const glide = new GlideClient();
const magicAuthCheckResponse = await glide.magicAuth.verifyAuth({
token: "code-from-user-device",
phoneNumber: "+555123456789"
});
if (magicAuthCheckResponse.verified) {
console.log("User verified");
} else {
console.log("User not verified");
}
}
main().catch(console.error);
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 the session. |
expiresAt | number | The expiration time of the session. |
scopes | string[] | An array of scopes associated with the session. |