Skip to main content
Version: Python

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. start_server_auth

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

Syntax:

async def start_server_auth(self, **kwargs) -> MagicAuthStartServerAuthResponse:

Parameters:

PropertyTypeDescription
phone_numberstrOptional - The phone number to verify
emailstrOptional - The email to verify
redirect_urlstrOptional - URL to redirect after verification
statestrOptional - A state value that can be used to maintain state between the client and server.
otp_confirmation_urlstrOptional - Custom URL for OTP confirmation page
rcs_confirmation_urlstrOptional - Custom URL for RCS waiting page
fallback_channelstrOptional - Fallback verification method ('SMS', 'EMAIL', 'RCS', or 'NO_FALLBACK')

At least one of phone_number 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:

PropertyTypeDescription
session_idstrUnique session identifier for this verification attempt
auth_urlstrURL where the user should be directed to complete verification

Example:

import asyncio
from glide_sdk import GlideClient

async def main():
glide = GlideClient()

# Start server auth with phone number
response = await glide.magic_auth.start_server_auth(
phone_number="+555123456789"
)

print(f"Session ID: {response['session_id']}")
print(f"Auth URL: {response['auth_url']}")

if __name__ == "__main__":
asyncio.run(main())

2. check_server_auth

Description: check_server_auth checks the status of a server-side verification initiated with start_server_auth.

Syntax:

async def check_server_auth(self, session_id: str) -> CheckServerAuthResponse:

Parameters:

PropertyTypeDescription
session_idstrThe session ID received from start_server_auth

Returns:

  • CheckServerAuthResponse: An object containing the verification status.

CheckServerAuthResponse Properties:

PropertyTypeDescription
statusstrCurrent status of the verification ('PENDING' or 'COMPLETED')
verifiedboolWhether the verification was successful (only meaningful when status is COMPLETED)

Example:

import asyncio
from glide_sdk import GlideClient

async def main():
glide = GlideClient()

# Check server auth status
response = await glide.magic_auth.check_server_auth(
session_id="session-id-from-start-server-auth"
)

if response["status"] == "COMPLETED":
if response["verified"]:
print("Verification successful!")
else:
print("Verification failed!")
else:
print("Verification still pending...")

if __name__ == "__main__":
asyncio.run(main())

3. start_auth

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

Syntax:

async def start_auth(self, **kwargs) -> MagicAuthStartResponse:

Parameters:

MagicAuthStartProps Properties:

PropertyTypeDescription
phone_numberstringOptional - The phone number to verify.
emailstringOptional - The email to verify.
fallback_channelstringOptional - Specifies the fallback verification method if the primary method fails. Can be 'SMS', 'EMAIL', or 'NO_FALLBACK'.
redirect_urlstringOptional - The URL to which the user will be redirected after a successful verification.
statestringOptional - A state value that can be used to maintain state between the client and server.
device_ip_addressstringOptional - The IP address of the user's device.

One of phone_number or email must be provided.

device_ip_address 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:

PropertyTypeDescription
typestringThe value can be MAGIC, SMS or EMAIL
authUrlstringOptional - The URL to open on the user's device in case of MAGIC type.
flatAuthUrlstringOptional - The plain URL to use .In case you do not want to redirect or to open at user's device use this.
operatorIdstringOptional - The OperatorId.

Example:

import asyncio
from glide_sdk import GlideClient

async def main():
glide = GlideClient()
magic_auth_start_response = await glide.magic_auth.start_auth(
phone_number="+555123456789"
)
if magic_auth_start_response["type"] == "MAGIC":
print(f"Open this URL on the user's device: {magic_auth_start_response['authUrl']}")
else:
print(f"Verification code sent to the user's device using channel {magic_auth_start_response['type']}")

if __name__ == "__main__":
main()

4. verify_auth

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

Syntax:

async def verify_auth(self, **kwargs) -> MagicAuthCheckResponse:

Parameters:

PropertyTypeDescription
codestringOptional - The code received from the user's device via EMAIL or SMS.
phone_numberstringOptional - The phone number to verify if SMS or MAGIC.
emailstringOptional - The email to verify in case of EMAIL
tokenstringOptional - The token received from the user's device in case of MAGIC.
device_ip_addressstringOptional - The IP address of the user's device.

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

  • MAGIC: token and phone_number
  • SMS: code and phone_number
  • EMAIL: code and email

Returns:

  • MagicAuthCheckResponse: A MagicAuthCheckResponse instance.

MagicAuthCheckResponse Properties:

PropertyTypeDescription
verifiedbooleanWhether the user is verified.

Example:

import asyncio
from glide_sdk import GlideClient

async def main():
glide = GlideClient()
magic_auth_check_response = await glide.magic_auth.verify_auth(
token="code-from-user-device",
phone_number="+555123456789"
)

if magic_auth_check_response.verified:
print("User verified")
else:
print("User not verified")

if __name__ == "__main__":
asyncio.run(main())

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

PropertyTypeDescription
sessionSessionAn optional session object for authentication and authorization.

Session

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

Properties

PropertyTypeDescription
accessTokenstringThe access token for the session.
expiresAtnumberThe expiration time of the session.
scopesstring[]An array of scopes associated with the session.