API Reference

Complete reference for Magical Auth API endpoints and SDK methods.

Testing the API

For interactive API testing, visit our Scalar API Reference.

Frontend SDK - PhoneAuthClient

Initialization

import { PhoneAuthClient } from 'glide-web-client-sdk';

const client = new PhoneAuthClient({
  endpoints: {
    prepare: '/api/phone-auth/prepare',
    process: '/api/phone-auth/process'
  },
  debug: true, // Enable debug logging
  onSuccess: (data) => {
    console.log('Success:', data);
  },
  onError: (error) => {
    console.error('Error:', error);
  },
  onRetryAttempt: (attempt, maxAttempts) => {
    console.log(`Retry ${attempt}/${maxAttempts}`);
  }
});

High-Level Methods

verifyPhoneNumberComplete(phoneNumber, options?)

Complete flow to verify phone ownership.

const result = await client.verifyPhoneNumberComplete('+14155551234', {
  consent_data: {
    consent_text: 'I agree to verify my phone number',
    policy_link: 'https://example.com/privacy',
    policy_text: 'Privacy Policy'
  }
});
// Returns: { verified: true, phone_number: '+14155551234' }

getPhoneNumberComplete(options?)

Complete flow to retrieve phone number from device.

const result = await client.getPhoneNumberComplete({
  plmn: { mcc: '310', mnc: '260' }, // Optional: specify carrier
  consent_data: {
    consent_text: 'I agree to verify my phone number',
    policy_link: 'https://example.com/privacy',
    policy_text: 'Privacy Policy'
  }
});
// Returns: { phone_number: '+14155551234' }

Granular Control Methods

For step-by-step control over the authentication process:

preparePhoneRequest(options)

Step 1: Initialize authentication session.

const prepareResponse = await client.preparePhoneRequest({
  use_case: UseCase.GET_PHONE_NUMBER, // or UseCase.VERIFY_PHONE_NUMBER
  phone_number: '+14155551234', // Required for verify flow
  plmn: { mcc: '310', mnc: '260' }, // Optional for get flow
  consent_data: { ... }
});
// Returns: PrepareResponse with authentication_strategy, session, and data

invokeSecurePrompt(prepareResponse)

Step 2: Trigger browser's Digital Credentials API.

const credential = await client.invokeSecurePrompt(prepareResponse);
// Returns: SecureCredentialResponse with vp_token

getPhoneNumber(credential, session)

Step 3A: Process credential to get phone number.

const result = await client.getPhoneNumber(credential, prepareResponse.session);
// Returns: { phone_number: '+14155551234' }

verifyPhoneNumber(credential, session)

Step 3B: Process credential to verify phone.

const result = await client.verifyPhoneNumber(credential, prepareResponse.session);
// Returns: { verified: true, phone_number: '+14155551234' }

Backend SDK - GlideClient

Initialization

import { GlideClient } from 'glide-sdk';

const glide = new GlideClient({
  apiKey: process.env.GLIDE_API_KEY,
  internal: {
    authBaseUrl: 'https://oidc.gateway-x.io',
    apiBaseUrl: 'https://api.glideidentity.app'
  }
});

Methods

magicAuth.prepare(request)

Prepare authentication request.

const response = await glide.magicAuth.prepare({
  use_case: 'GetPhoneNumber', // or 'VerifyPhoneNumber'
  phone_number: '+14155551234', // Optional for GetPhoneNumber
  plmn: { mcc: '310', mnc: '260' }, // Optional
  consent_data: { ... },
  client_info: { 
    user_agent: req.headers['user-agent'],
    platform: 'web'
  }
});

magicAuth.getPhoneNumber(request)

Process get phone number request.

const result = await glide.magicAuth.getPhoneNumber({
  session: { session_key: 'sess_xxx' },
  vp_token: { glide: credential }
});
// Returns: { phone_number: '+14155551234' }

magicAuth.verifyPhoneNumber(request)

Process verify phone number request.

const result = await glide.magicAuth.verifyPhoneNumber({
  session: { session_key: 'sess_xxx' },
  vp_token: { glide: credential }
});
// Returns: { verified: true, phone_number: '+14155551234' }

Type Definitions

PhoneAuthOptions

interface PhoneAuthOptions {
  use_case: 'GetPhoneNumber' | 'VerifyPhoneNumber';
  phone_number?: string; // E.164 format
  plmn?: {
    mcc: string; // Mobile Country Code
    mnc: string; // Mobile Network Code
  };
  consent_data?: {
    consent_text: string;
    policy_link: string;
    policy_text: string;
  };
}

PrepareResponse

interface PrepareResponse {
  authentication_strategy: 'ts43' | 'link';
  session: {
    session_key: string;
    nonce?: string;
    enc_key?: string;
  };
  data: TS43Data | LinkData;
}

Error Response

interface MagicAuthError {
  code: string;
  message: string;
  status?: number;
  request_id?: string;
  timestamp?: string;
  details?: any;
}

Error Codes

Code	Status	Description
CARRIER_NOT_ELIGIBLE	422	Carrier doesn't support Magical Auth
INVALID_PHONE_NUMBER	400	Phone number format is invalid
SESSION_EXPIRED	404	Session has expired
PHONE_NUMBER_MISMATCH	422	Phone doesn't match SIM card
INVALID_CREDENTIAL	422	Invalid or expired credential
RATE_LIMIT_EXCEEDED	429	Too many requests
USE_CASE_MISMATCH	422	Use case doesn't match session

Browser Requirements

• Chrome 119+ with Digital Credentials flag enabled
• Edge 119+ with experimental features enabled
• Safari and Firefox coming soon

Enable in Chrome: chrome://flags/#digital-credentials

Framework Integrations

Vue Composable

import { usePhoneAuth } from 'glide-web-client-sdk/vue';

const { getPhoneNumber, verifyPhoneNumber, isSupported } = usePhoneAuth(config);

React Hook

import { usePhoneAuth } from 'glide-web-client-sdk/react';

const { getPhoneNumber, verifyPhoneNumber, isSupported } = usePhoneAuth(config);

Testing

For testing without a physical device:

1. Use AirDroid Web for remote Android access
2. Use ngrok to expose local development: ngrok http 3000
3. Deploy to Vercel or Cloud Run for production testing

See Error Handling Guide for handling edge cases.