Version: Go

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.

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:

StartServerAuth(props types.MagicAuthStartProps, conf types.ApiConfig) (*types.MagicAuthStartServerAuthResponse, error)

Parameters:

Parameter	Type	Description
`props`	`MagicAuthStartProps`	A struct containing the start auth properties.
`conf`	`ApiConfig`	A struct 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 - 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`	`FallbackVerificationChannel`	Optional - Fallback verification method ('SMS', 'EMAIL', or 'NO_FALLBACK')

At least one of PhoneNumber or Email must be provided.

Returns:

*types.MagicAuthStartServerAuthResponse: A struct 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 (
    "github.com/GlideApis/sdk-go/pkg/glide"
    "github.com/GlideApis/sdk-go/pkg/types"
)

func main() {
    glideClient, err := glide.NewGlideClient(settings)
    if err != nil {
        panic(err)
    }
    
    // Start server auth with phone number
    startResponse, err := glideClient.MagicAuth.StartServerAuth(types.MagicAuthStartProps{
        PhoneNumber: "+555123456789",
    }, types.ApiConfig{SessionIdentifier: "magic_auth_server_test"})
    
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Session ID: %s\n", startResponse.SessionID)
    fmt.Printf("Auth URL: %s\n", startResponse.AuthURL)
}

2. `CheckServerAuth`

Description: CheckServerAuth checks the status of a server-side verification initiated with StartServerAuth.

Syntax:

CheckServerAuth(sessionID string, conf types.ApiConfig) (*types.MagicAuthCheckServerAuthResponse, error)

Parameters:

Property	Type	Description
`sessionID`	`string`	The session ID received from StartServerAuth

Returns:

*types.MagicAuthCheckServerAuthResponse: A struct containing the verification status.

MagicAuthCheckServerAuthResponse Properties:

Property	Type	Description
`Status`	`string`	Current status of the verification ('PENDING' or 'COMPLETED')
`Verified`	`bool`	Whether the verification was successful (only meaningful when status is COMPLETED)

Example:

import (
    "github.com/GlideApis/sdk-go/pkg/glide"
    "github.com/GlideApis/sdk-go/pkg/types"
)

func main() {
    glideClient, err := glide.NewGlideClient(settings)
    if err != nil {
        panic(err)
    }
    
    // Check server auth status
    checkResponse, err := glideClient.MagicAuth.CheckServerAuth(
        "session-id-from-start-server-auth",
        types.ApiConfig{SessionIdentifier: "magic_auth_server_test"},
    )
    
    if err != nil {
        panic(err)
    }
    
    if checkResponse.Status == "COMPLETED" {
        if checkResponse.Verified {
            fmt.Println("Verification successful!")
        } else {
            fmt.Println("Verification failed!")
        }
    } else {
        fmt.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:

StartAuth(props types.MagicAuthStartProps, conf types.ApiConfig) (*MagicAuthStartResponse, error)

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
`FallbackChannel`	`FallbackVerificationChannel`	Optional - Fallback verification method
`DeviceIPAddress`	`string`	Optional - IP address of the end-user's device

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: A struct 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 if you don't want to redirect
`OperatorId`	`string`	Optional - The OperatorId

Example:

import (
    "github.com/GlideApis/sdk-go/pkg/glide"
    "github.com/GlideApis/sdk-go/pkg/types"
)

func main() {
    glideClient, err := glide.NewGlideClient(settings)
    if err != nil {
        panic(err)
    }
    
    startResponse, err := glideClient.MagicAuth.StartAuth(types.MagicAuthStartProps{
        PhoneNumber: "+555123456789",
    }, types.ApiConfig{SessionIdentifier: "magic_auth_test"})
    
    if err != nil {
        panic(err)
    }

    if startResponse.Type == "MAGIC" {
        fmt.Printf("Open this URL on the user's device: %s\n", startResponse.AuthURL)
    } else {
        fmt.Printf("Verification code sent to the user's device using channel %s\n", startResponse.Type)
    }
}

4. `VerifyAuth`

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

Syntax:

VerifyAuth(props types.MagicAuthVerifyProps, conf types.ApiConfig) (*MagicAuthVerifyRes, error)

Parameters:

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 - IP address of the end-user's device

Two parameters need to be sent based on the Type received from the StartAuth method:

MAGIC: Token and PhoneNumber
SMS: Code and PhoneNumber
EMAIL: Code and Email

Returns:

*MagicAuthVerifyRes: A struct containing the verification result.

MagicAuthVerifyRes Properties:

Property	Type	Description
`Verified`	`bool`	Whether the user is verified

Example:

import (
    "github.com/GlideApis/sdk-go/pkg/glide"
    "github.com/GlideApis/sdk-go/pkg/types"
)

func main() {
    glideClient, err := glide.NewGlideClient(settings)
    if err != nil {
        panic(err)
    }

    verifyResponse, err := glideClient.MagicAuth.VerifyAuth(types.MagicAuthVerifyProps{
        PhoneNumber: "+555123456789",
        Token:      "token-from-auth-response",
    }, types.ApiConfig{SessionIdentifier: "magic_auth_test"})

    if err != nil {
        panic(err)
    }

    if verifyResponse.Verified {
        fmt.Println("User verified")
    } else {
        fmt.Println("User not verified")
    }
}

Error Handling

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

Invalid input parameters
Network or service unavailability issues
Authentication errors
Invalid session errors

Type Definitions

ApiConfig

Configuration object for API requests.

Properties

Property	Type	Description
`SessionIdentifier`	`string`	Optional - Identifier for the session
`Session`	`*Session`	Optional - Session object for authentication

Session

Object representing a user session with an access token, expiration time, and associated scopes.

Properties

Property	Type	Description
`AccessToken`	`string`	The access token for authentication
`ExpiresAt`	`int64`	Unix timestamp when the session expires
`Scopes`	`[]string`	List of authorization scopes

FallbackVerificationChannel

Enum defining possible fallback verification methods:

const (
    SMS         FallbackVerificationChannel = "SMS"
    EMAIL       FallbackVerificationChannel = "EMAIL"
    NO_FALLBACK FallbackVerificationChannel = "NO_FALLBACK"
)

Magical Auth Reference

MagicAuthClient Reference​

Methods​

1. StartServerAuth​

2. CheckServerAuth​

3. StartAuth​

4. VerifyAuth​

Error Handling​

Type Definitions​

ApiConfig​

Properties​

Session​

Properties​

FallbackVerificationChannel​

MagicAuthClient Reference

Methods

1. `StartServerAuth`

2. `CheckServerAuth`

3. `StartAuth`

4. `VerifyAuth`

Error Handling

Type Definitions

ApiConfig

Properties

Session

Properties

FallbackVerificationChannel