Widget Setup - Authiqa Documentation

<div id="authiqa"></div>

<script 
    defer

    src="https://widget.authiqa.com"
    data-public-key="YOUR_PUBLIC_KEY"
    action="signin"
></script>

Configuration Options

The widget supports these configuration attributes:

Required Attributes

data-public-key: Your PUBLIC key
action: Authentication action (signin, signup, reset, update, verify, resend)
defer: For proper script loading

Optional Attributes

theme: "light" (default) or "dark"
preset: Select a predefined design preset. One of modern, classic, corporate, sharp, minimal
disable-styles: "true" or "false" (default)
termsAndConditions: URL for terms and conditions page
privacy: URL for privacy policy
notificationSettings: URL for notification settings
buttonName: Custom text for submit button
data-messages: JSON string containing custom success and loading messages
successAuthPath: Custom URL to redirect after successful sign in
signinAuthPath: Custom URL to redirect after email verification
verifyAuthPath: Custom URL for email verification page
updatePasswordPath: Custom URL for password update page
resendAuthPath: Custom URL for resend verification page
resetAuthPath: Custom URL for password reset page
data-customization: JSON string containing layout and styling customizations
action: Authentication action (optional if URL contains action)

URL-Based Action Detection

The widget can automatically detect the authentication action from the URL if no action attribute is provided in the script tag. It will scan the URL for any of the valid actions (signin, signup, verify, reset, update, resend).

<!-- No action attribute needed if URL contains the action -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_PUBLIC_KEY"
></script>

For example:

If the URL is https://example.com/auth/signup, the widget will show the signup form
If the URL is https://example.com/verify?token=abc123, the widget will show the verification form
If the URL is https://example.com/auth#reset, the widget will show the password reset form

If both the URL contains an action and the script tag has an action attribute, the attribute in the script tag takes precedence.

Direct CSS Styling

In addition to using the data-customization attribute, you can directly style the widget elements using CSS selectors. The widget uses specific class names that you can target in your stylesheets:

<head>
    <style>
        /* Container styling */
        .authiqa-container {
            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15) !important;
            border: none !important;
        }
        
        /* Title styling */
        .authiqa-container h1,
        #authiqa h1 {
            font-family: 'Georgia', serif !important;
            letter-spacing: 2px !important;
            color: #333 !important;
        }
        
        /* Input styling */
        .authiqa-container .authiqa-input,
        input.authiqa-input {
            border: 2px solid #6200ea !important;
            border-radius: 25px !important;
            padding: 16px !important;
        }
        
        /* Button styling */
        .authiqa-container .authiqa-button,
        button.authiqa-button {
            text-transform: uppercase !important;
            font-weight: bold !important;
            letter-spacing: 1px !important;
        }
        
        /* Terms container styling */
        .authiqa-container .terms-container {
            margin-bottom: 2rem !important; /* Increased spacing before button */
        }
    </style>
</head>

CSS Class Reference

The widget uses the following CSS classes that you can target for custom styling:

CSS Class	Element	Description
`.authiqa-container`	Main container	The outer container of the widget
`.authiqa-title`	Title	The main heading (h1) of the form
`.authiqa-input`	Input fields	All input fields (email, password, etc.)
`.authiqa-button`	Submit button	The main action button
`.authiqa-password-container`	Password field wrapper	Container for password input and toggle
`.password-toggle`	Password visibility toggle	Button to show/hide password
`.authiqa-error`	Error message	Container for error messages
`.authiqa-success`	Success message	Container for success messages
`.authiqa-form`	Form element	The form element containing inputs
`.authiqa-label`	Input labels	Labels above input fields
`.authiqa-labeled-input`	Label+input container	Container for label and input pairs
`.terms-container`	Terms checkbox area	Container for terms and conditions checkbox and text

When styling the widget with CSS, use the !important flag to ensure your styles override the default styles. For more complex customizations, you can use the disable-styles="true" attribute and apply your own styles from scratch.

Combined Example with Custom CSS and URL-Based Action

This example shows how to combine custom CSS styling with URL-based action detection:

<!DOCTYPE html>
<html>
<head>
    <title>Custom Styled Authiqa Widget</title>
    <style>
        /* Custom styling for the widget */
        .authiqa-container {
            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15) !important;
            border-radius: 16px !important;
        }
        
        /* Input styling */
        .authiqa-container .authiqa-input {
            border: 2px solid #6200ea !important;
            border-radius: 25px !important;
        }
        
        /* Button styling */
        .authiqa-container .authiqa-button {
            text-transform: uppercase !important;
            font-weight: bold !important;
            background-color: #6200ea !important;
        }
    </style>
</head>
<body>
    <div id="authiqa"></div>
    <script
        src="https://widget.authiqa.com"
        defer
        data-public-key="YOUR_PUBLIC_KEY"
        data-customization='{
            "colors": {
                "buttonText": "#ffffff"
            }
        }'
    ></script>
</body>
</html>

Advanced Customization

The widget supports extensive customization through the data-customization attribute:

Page and Form Layout

{
    "pageLayout": {
        "backgroundColor": "#f5f5f5",
        "formPosition": "center",
        "formMarginTop": "50px",
        "formMarginBottom": "50px"
    },
    "layout": {
        "padding": "1.5rem",
        "margin": "1rem",
        "borderRadius": "8px",
        "maxWidth": "350px"
    }
}

Colors and Typography

{
    "colors": {
        "background": "#ffffff",
        "buttonBackground": "#007bff",
        "buttonText": "#ffffff",
        "inputBackground": "#f8f9fa",
        "inputText": "#333333",
        "inputPlaceholder": "#a3a3a3",
        "borderColor": "#dee2e6"
    },
    "typography": {
        "titleText": {
            "signinText": "Welcome Back",
            "signupText": "Create Account",
            "resetText": "Reset Password",
            "updateText": "Update Password",
            "verifyText": "Verify Email",
            "resendText": "Resend Confirmation"
        },
        "titleSize": "1.8rem",
        "titleColor": "#333333",
        "fontFamily": "Arial, sans-serif",
        "termsText": {
            "agreePrefix": "I agree with the",
            "andConnector": "and",
            "defaultPrefix": "default",
            "linkText": {
                "terms": "Terms of Service",
                "privacy": "Privacy Policy",
                "notifications": "Notification Settings"
            },
            "textColor": "#333333",
            "linkColor": "#007bff"
        }
    }
}

Input Fields and Buttons

{
    "inputs": {
        // Placeholder customization
        "emailPlaceholder": "Enter your email",
        "passwordPlaceholder": "Enter your password",
        "usernamePlaceholder": "Choose a username",
        "confirmPasswordPlaceholder": "Confirm your password",

        // Label text customization
        "emailLabel": "Email Address",
        "passwordLabel": "Password",
        "usernameLabel": "Username",
        "confirmPasswordLabel": "Confirm Password",

        // Input field styling
        "height": "48px",
        "width": "100%",
        "padding": "12px 16px",
        "margin": "8px 0",
        "fontSize": "16px",
        "fontWeight": "400",
        "borderRadius": "8px",
        "focusBorderColor": "#10D5C6",
        "focusBoxShadow": "0 0 0 2px rgba(16, 213, 198, 0.25)",
        "placeholderAlign": "left"
    },
    "buttons": {
        "signinText": "Sign In",
        "signupText": "Sign Up",
        "resetText": "Reset Password",
        "updateText": "Update Password",
        "verifyText": "Verify Email",
        "resendText": "Resend Confirmation",
        "height": "45px",
        "width": "100%",
        "borderRadius": "25px"
    }
}

Each authentication action (signin, signup, reset, update, verify, resend) has corresponding customizable text for both its title and button. This allows for complete white-labeling of all authentication forms.All labels are properly associated with their input fields using the for attribute for improved accessibility. This allows users to click on labels to focus the corresponding input field and improves screen reader compatibility.

Input Field Customization Options

The widget now supports extensive customization of input fields through the customization.inputs object:

Property	Type	Description	Example
`emailPlaceholder`	string	Placeholder text for email input	”Your work email”
`passwordPlaceholder`	string	Placeholder text for password input	”Create a strong password”
`usernamePlaceholder`	string	Placeholder text for username input	”Choose a username”
`confirmPasswordPlaceholder`	string	Placeholder text for confirm password input	”Re-enter your password”
`emailLabel`	string	Label text for email input	”Email Address”
`passwordLabel`	string	Label text for password input	”Password”
`usernameLabel`	string	Label text for username input	”Username”
`confirmPasswordLabel`	string	Label text for confirm password input	”Confirm Password”
`height`	string	Height of input fields	”48px”
`width`	string	Width of input fields	”100%“
`padding`	string	Padding inside input fields	”12px 16px”
`margin`	string	Margin around input fields	”8px 0”
`fontSize`	string	Font size of input text	”16px”
`fontWeight`	string	Font weight of input text	”400”
`borderRadius`	string	Border radius of input fields	”8px”
`focusBorderColor`	string	Border color when input is focused	”#10D5C6”
`focusBoxShadow`	string	Box shadow when input is focused	”0 0 0 2px rgba(16, 213, 198, 0.25)“
`placeholderAlign`	string	Text alignment for placeholder text	”left”, “center”, “right”

Complete Customization Example

<script
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_PUBLIC_KEY"
    action="signup"
    data-customization='{
        "pageLayout": {
            "backgroundColor": "#f5f5f5",
            "formPosition": "center"
        },
        "layout": {
            "padding": "2rem",
            "borderRadius": "10px"
        },
        "colors": {
            "background": "#ffffff",
            "buttonBackground": "#4CAF50",
            "buttonText": "#ffffff",
            "inputPlaceholder": "#a3a3a3"
        },
        "typography": {
            "titleText": {
                "signupText": "Join Our Community"
            },
            "titleSize": "2rem",
            "termsText": {
                "textColor": "#555555",
                "linkColor": "#4CAF50"
            }
        },
        "inputs": {
            "emailPlaceholder": "Your email address",
            "emailLabel": "Work Email",
            "passwordPlaceholder": "Create a strong password",
            "passwordLabel": "Create Password",
            "usernameLabel": "Choose Username",
            "height": "48px",
            "borderRadius": "8px",
            "focusBorderColor": "#4CAF50"
        },
        "buttons": {
            "signupText": "Create Account"
        }
    }'
></script>

Labels follow accessibility best practices by being properly associated with their input fields using the for attribute. This improves usability for screen readers and allows users to click on the label to focus the input field.

Presets

Authiqa includes built‑in visual presets to quickly match popular design aesthetics. You can apply a preset with the preset attribute on the script tag or programmatically via the widget API. Supported presets:

modern
classic
corporate
sharp
minimal

Apply a preset (script tag)

<div id="authiqa"></div>
<script
  defer
  src="https://widget.authiqa.com"
  data-public-key="YOUR_PUBLIC_KEY"
  action="signin"
  preset="modern"
></script>

Apply a preset (programmatically)

<div id="authiqa"></div>
<script defer src="https://widget.authiqa.com" data-public-key="YOUR_PUBLIC_KEY"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    const widget = new window.AuthiqaWidget({
      publicKey: 'YOUR_PUBLIC_KEY',
      container: 'authiqa',
      mode: 'popup',
      theme: 'light',
      preset: 'classic' // initial preset
    });

    // Later in runtime you can switch presets
    widget.applyPreset('sharp');
  });
</script>

Customizing on top of a preset

You can provide customization overrides alongside a preset. The preset provides a complete customization baseline that is deeply merged with your overrides.

<script
  defer
  src="https://widget.authiqa.com"
  data-public-key="YOUR_PUBLIC_KEY"
  action="signup"
  preset="corporate"
  data-customization='{
    "colors": {
      "buttonBackground": "#0ea5e9",
      "buttonText": "#ffffff"
    },
    "typography": {
      "titleText": { "signupText": "Join Our Platform" }
    }
  }'
></script>

Key areas you can override in data-customization include:

pageLayout: background, form positioning, margins
layout: padding, borderRadius, width/height constraints
colors: background, buttonBackground, buttonText, input colors, borderColor
typography: titleText, sizes, weights, fonts, terms text, link colors
inputs: labels, placeholders, sizes, borders, focus styles
buttons: labels, sizes, radii, hover colors
navLinks: prompts and link text
passwordToggle: icon color/placement

Preset summaries

modern: Dark background, blue primary buttons, modern typography and subtle shadows. Great for contemporary apps.
classic: Light background, blue accents, rounded inputs, centered titles. Familiar and clean.
corporate: Professionally inspired look, Segoe UI typography, conservative borders and spacing.
sharp: Dark theme with high contrast and pill buttons.
minimal: Large headings, clean light layout with purple accents.

GitHub SSO Integration

Authiqa also includes built-in support for GitHub Single Sign-On (SSO). When GitHub SSO is enabled for your organization, the widget automatically displays a “Continue with GitHub” button on Sign In and Sign Up forms.

Quick Setup Checklist

GitHub account and organization (optional)
GitHub OAuth App with Client ID and Client Secret
Authorization callback URL configured
Authiqa organization updated with GitHub credentials

GitHub SSO Features

GitHub Sign-In Button

Automatically appears below the main submit button on Sign In and Sign Up forms
Only displayed when GitHub SSO is enabled for your organization
Styled to match your widget’s theme and customization
Handles both sign-in and sign-up flows using a unified callback

Unified OAuth Callback

Uses a single callback URL for both Sign In and Sign Up flows
Source context (signin/signup) is encoded in the OAuth state parameter
The widget validates the state parameter for security
After success, user is redirected to successAuthPath (or default success URL)

How GitHub SSO Works

The widget fetches your organization details and detects whether GitHub SSO is enabled and has a valid Client ID
If enabled, a GitHub button is rendered below the main submit button
When clicked, the widget initiates GitHub OAuth by redirecting the user to https://github.com/login/oauth/authorize
- It passes client_id, redirect_uri, scope=read:user user:email, and a signed state payload
- The redirect_uri uses your configured signinAuthPath (or current page) because GitHub supports a single callback
After GitHub redirects back with code and state, the widget detects the callback and exchanges the code via your API at /auth/github
On success, tokens are stored, a success message is shown, and the user is redirected to successAuthPath (or default success URL)

GitHub OAuth App Setup Guide

Follow these steps to create a GitHub OAuth App and configure your Authiqa organization.

Step 1: Create a GitHub OAuth App

Go to GitHub > Settings > Developer settings > OAuth Apps
Click “New OAuth App”
Fill out the form:
- Application name: Your app name
- Homepage URL: Your site URL (e.g., https://yourdomain.com)
- Authorization callback URL: Your sign-in page URL or the page where the widget is mounted (e.g., https://yourdomain.com/auth/signin)
Click “Register application”

Step 2: Get Your Credentials

After creating the OAuth App:

Copy the Client ID
Generate a new Client Secret and save it securely

Step 3: Configure Authiqa Organization

Update your Authiqa organization with the GitHub credentials:

curl -X PUT https://api.authiqa.com/organizations/{organization_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "githubClientId": "YOUR_GITHUB_CLIENT_ID",
    "githubClientSecret": "YOUR_GITHUB_CLIENT_SECRET",
    "githubSSOEnabled": true
  }'

Replace {organization_id} with your actual organization ID and use your API token from the Authiqa dashboard.

Configuration Requirements

Once configured, the widget will automatically:

Detect that GitHub SSO is enabled
Render the GitHub button on Sign In and Sign Up
Handle the OAuth flow and error messaging

Testing Your GitHub SSO Setup

Local Development

For testing on localhost, use a callback URL like:

http://localhost:3000/auth/signin

Then set this exact URL in your GitHub OAuth App under “Authorization callback URL”.

Verification Steps

Verify your organization configuration via the Get Organization Details API
Load your auth page and check that the GitHub button appears
Click the GitHub button and complete authentication
Confirm you are redirected to your configured successAuthPath

Common GitHub SSO Issues

GitHub Button Not Appearing

Possible Causes:

GitHub SSO not enabled in organization settings
Invalid or missing GitHub Client ID
Domain restrictions preventing widget load

Solutions:

Verify organization configuration via API
Check GitHub Client ID in organization settings
Ensure your domain is properly configured

OAuth Callback Errors

Possible Causes:

Callback URL mismatch between widget page and GitHub App settings
Invalid or missing state parameter
Network errors during code exchange

Solutions:

Ensure signinAuthPath (or page URL) exactly matches the GitHub App callback URL
Do not modify the state parameter
Check network and server logs for /auth/github

GitHub SSO Example

<div id="authiqa"></div>
<script
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_PUBLIC_KEY"
    action="signin"
></script>
<!-- GitHub SSO button will automatically appear if enabled -->

Notes on GitHub Flow

GitHub supports a single callback URL; the widget always uses signinAuthPath (or current page) for redirect
The widget encodes the source action (signin/signup) in the state parameter and validates it on return
After success, the widget stores tokens and redirects to successAuthPath
The widget also dismisses Google One Tap after a successful GitHub authentication to prevent overlapping prompts

Security Best Practices for GitHub SSO

Use HTTPS in production
Keep your Client Secret private
Validate the state parameter server-side
Verify the OAuth app callback URLs are exact matches

Troubleshooting Tips

Check your browser console for “Processing GitHub authentication…” messages during the callback
Ensure your backend /auth/github endpoint returns JSON with { success: true, token, user, jwtSecret } on success
If you see errors like “GitHub authentication unauthorized”, verify your client credentials and scopes

Coexistence with Google SSO

When both Google and GitHub SSO are enabled:

The GitHub button appears first, then the Google button below it
Google One Tap may appear after the buttons render (if enabled)
On successful GitHub auth, the widget dismisses Google One Tap to avoid conflicting prompts

<div id="authiqa"></div>
<script
  defer
  src="https://widget.authiqa.com"
  data-public-key="YOUR_PUBLIC_KEY"
  action="signin"
></script>
<!-- If both providers are enabled, both buttons will appear automatically -->

<div id="authiqa"></div>
<script
  defer
  src="https://widget.authiqa.com"
  data-public-key="YOUR_PUBLIC_KEY"
  action="signup"
></script>
<!-- The same GitHub button and flow applies for sign-up -->

Redirect Behavior

Successful auth redirects to: successAuthPath or the API-provided success URL
Errors display inline messages and do not redirect

Rate Limiting and State Cleanup

The widget stores a short-lived random state token in sessionStorage and removes it after handling the callback
If the callback URL is reloaded without valid state, the widget won’t process it

Configuration Summary (GitHub)

Setting	Where	Value
Client ID	GitHub OAuth App	YOUR_GITHUB_CLIENT_ID
Client Secret	GitHub OAuth App	YOUR_GITHUB_CLIENT_SECRET
Authorization callback URL	GitHub OAuth App	e.g., https://yourdomain.com/auth/signin
signinAuthPath	Widget attribute	Path or absolute URL for callback page
successAuthPath	Widget attribute	Post-auth redirect destination

The widget includes advanced Google One Tap integration that can be controlled with the enable-google-one-tap attribute:

<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_PUBLIC_KEY"
    action="signin"
    enable-google-one-tap="true"
></script>

Google SSO Integration

The Authiqa widget includes built-in support for Google Single Sign-On (SSO) authentication. When Google SSO is enabled for your organization, the widget automatically displays Google authentication options without requiring additional configuration.

Quick Setup Checklist

Before diving into the detailed setup, here’s a quick checklist of what you need:

Google Cloud Console account
Google OAuth 2.0 Client ID and Secret
Authorized JavaScript Origins configured
Authorized Redirect URIs configured (including Authiqa callback)
Google+ API enabled
OAuth Consent Screen configured
Authiqa organization updated with Google credentials

Google SSO Features

Google Sign-In Button

Automatically appears below the main submit button on Sign In and Sign Up forms
Only displayed when Google SSO is enabled for your organization
Styled to match your widget’s theme and customization
Handles both sign-in and sign-up flows seamlessly

Google One Tap

Displays Google’s One Tap prompt for streamlined authentication
Appears after the Google button is rendered (with a short delay)
Only shown once per session to avoid repetitive prompts
Provides the fastest authentication experience for returning users

How Google SSO Works

Automatic Detection: The widget checks if Google SSO is enabled for your organization
Dynamic Rendering: If enabled, a Google Sign-In/Sign-Up button appears below the main form
One Tap Integration: Google One Tap prompt may appear for eligible users
Error Handling: Clear error messages are displayed if Google authentication fails
Token Management: Successful Google authentication follows the same token storage as regular authentication

Google SSO Setup Guide

To enable Google SSO for your Authiqa widget, you need to configure Google OAuth credentials and update your organization settings. Follow this step-by-step guide:

Step 1: Create Google OAuth Credentials

Go to Google Cloud Console
- Visit Google Cloud Console
- Sign in with your Google account
Create or Select a Project
- If you don’t have a project, click “Create Project”
- Give your project a name (e.g., “My App Authentication”)
- Click “Create”
Enable Google+ API
- In the left sidebar, go to “APIs & Services” > “Library”
- Search for “Google+ API”
- Click on it and press “Enable”
Configure OAuth Consent Screen
- Go to “APIs & Services” > “OAuth consent screen”
- Choose “External” for user type (unless you’re using Google Workspace)
- Fill in the required information:
  - App name: Your application name
  - User support email: Your support email
  - Developer contact information: Your email
- Add your domain to “Authorized domains” (e.g., yourdomain.com)
- Save and continue through the remaining steps
Create OAuth 2.0 Credentials
- Go to “APIs & Services” > “Credentials”
- Click “Create Credentials” > “OAuth 2.0 Client IDs”
- Choose “Web application” as the application type
- Give it a name (e.g., “Authiqa Widget”)

Step 2: Configure Authorized URLs

In the OAuth 2.0 client configuration, you need to add your authorized URLs: Authorized JavaScript Origins:

https://yourdomain.com
https://www.yourdomain.com
http://localhost:3000  (for local development)

Authorized Redirect URIs:

https://yourdomain.com
https://www.yourdomain.com
https://yourdomain.com/auth/callback
https://api.authiqa.com/auth/google/callback
http://localhost:3000  (for local development)

Replace yourdomain.com with your actual domain. Include both www and non-www versions if you use both. Always include the Authiqa callback URL: https://api.authiqa.com/auth/google/callback

Step 3: Get Your Credentials

After creating the OAuth client:

Copy the Client ID
- You’ll see a “Client ID” that looks like: 123456789-abcdefghijklmnop.apps.googleusercontent.com
- Copy this value
Copy the Client Secret
- You’ll also see a “Client secret”
- Copy this value as well

Step 4: Configure Authiqa Organization

Use the Authiqa API to configure Google SSO for your organization:

curl -X PUT https://api.authiqa.com/organizations/{organization_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "googleClientId": "YOUR_GOOGLE_CLIENT_ID",
    "googleClientSecret": "YOUR_GOOGLE_CLIENT_SECRET",
    "googleSSOEnabled": true
  }'

Replace {organization_id} with your actual organization ID, and use your API token. You can find these values in your Authiqa dashboard.

Configuration Requirements

Once you’ve completed the setup above, no additional configuration is needed in the widget code. The Google SSO feature is automatically handled based on your organization’s backend settings. The widget will:

Automatically detect that Google SSO is enabled
Display the Google Sign-In/Sign-Up button
Handle the authentication flow seamlessly

Testing Your Google SSO Setup

Local Development Setup

For testing during development, add localhost URLs to your Google OAuth configuration: Authorized JavaScript Origins:

http://localhost:3000
http://localhost:8080
http://127.0.0.1:3000

Authorized Redirect URIs:

http://localhost:3000
http://localhost:8080
http://127.0.0.1:3000
https://api.authiqa.com/auth/google/callback

Verification Steps

Check Google Console: Ensure your OAuth client is properly configured
Verify API Response: Use the Get Organization Details API to confirm Google SSO is enabled
Test the Widget: Load your authentication page and verify the Google button appears
Test Authentication: Try signing in with a Google account

Common Google SSO Issues

Google Button Not Appearing

Possible Causes:

Google SSO not enabled in organization settings
Invalid or missing Google Client ID
Domain restrictions preventing widget load

Solutions:

Verify organization configuration via API
Check Google Client ID in organization settings
Ensure domain is properly configured

Authentication Errors

Possible Causes:

Incorrect redirect URIs in Google Console
Missing Authiqa callback URL
Domain mismatch between widget and Google config

Solutions:

Add all required redirect URIs
Include https://api.authiqa.com/auth/google/callback
Verify domain consistency

Google SSO Example

<div id="authiqa"></div>
<script
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_PUBLIC_KEY"
    action="signin"
></script>
<!-- Google SSO button will automatically appear if enabled -->

Google One Tap Configuration

The widget includes advanced Google One Tap integration that can be controlled with the enable-google-one-tap attribute:

<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_PUBLIC_KEY"
    action="signin"
    enable-google-one-tap="true"
></script>

Google One Tap Behavior

Google One Tap provides a streamlined authentication experience for users already logged into their Google accounts. The widget implements several optimizations for One Tap:

Delayed Rendering: One Tap is shown with a short delay after the Google button to prevent UI interference
Session Management: One Tap is only shown once per session to avoid repetitive prompts
Form Switching: One Tap is automatically dismissed when switching between authentication forms
Success Tracking: One Tap is not shown again after a successful authentication
SPA Support: One Tap is properly managed in Single Page Applications to prevent persistence issues

Controlling Google One Tap

You can control Google One Tap behavior in several ways:

Enable/Disable: Set enable-google-one-tap="false" to completely disable One Tap while still showing the Google Sign-In button
Reset on Sign Out: Call widget.resetGoogleOneTap() when a user signs out to allow One Tap to appear again in the same session
Cleanup: Call widget.cleanup() when removing the widget from the DOM to ensure One Tap is properly dismissed

The widget provides two Google authentication methods:

Google Sign-In Button: Always appears when Google SSO is enabled for your organization
Google One Tap: Appears as a popup prompt only when enabled and appropriate for the user’s context

Google One Tap is only shown on Sign In and Sign Up forms, not on other authentication forms like password reset or email verification.

Required Google Console Settings Summary

For quick reference, here are the essential settings needed in Google Cloud Console:

Setting	Value	Notes
API	Google+ API	Must be enabled
OAuth Consent Screen	Configured with your app details	Include your domain in authorized domains
Application Type	Web application	Required for web-based authentication
JavaScript Origins	Your domain(s) + localhost for testing	Include both www and non-www versions
Redirect URIs	Your domain(s) + Authiqa callback	Must include `https://api.authiqa.com/auth/google/callback`

Google Authentication Flow

The Google SSO integration supports both authentication flows:

Sign In: Existing users can sign in with their Google account
Sign Up: New users can create an account using their Google credentials
Account Linking: Users can link their existing Authiqa account with Google

Error Handling

If Google authentication encounters an error, the widget displays clear error messages:

Network connectivity issues
Invalid Google credentials
Account linking conflicts
Organization-specific restrictions

Google SSO Security Best Practices

Domain Security

Authorized Domains:

Only add domains you control
Use HTTPS in production
Avoid wildcard domains
Regularly review authorized domains

Credential Management

Client Secrets:

Store client secrets securely
Never expose secrets in frontend code
Rotate credentials periodically
Use environment variables for secrets

Important: Use separate Google OAuth clients for different environments (development, staging, production) to maintain security isolation and proper URL configuration.

Google SSO availability depends on your organization’s configuration. Contact your administrator if you expect to see Google authentication options but they don’t appear.

Custom Messages

The widget supports customizable messages for success and loading states:

{
    // Success messages
    signinSuccess: string;
    signupSuccess: string;
    resetSuccess: string;
    updateSuccess: string;
    resendSuccess: string;
    verificationSuccess: string;
    
    // Loading messages
    signinLoading: string;
    signupLoading: string;
    resetLoading: string;
    updateLoading: string;
    resendLoading: string;
    verificationLoading: string;
}

Error messages are not customizable as they display original server responses with error codes for better debugging.

Message Behavior

Display Duration

Success messages: 2 seconds
Error messages: 5 seconds
Loading messages: During processing

Message Types

Success messages: Green with checkmark
Loading messages: Below submit button
Error messages: Red with error code

If no custom messages are provided, the widget will use default messages. You can customize either success or loading messages independently.

Authentication Paths

The widget supports custom redirection paths for different authentication flows. Some of these paths also affect the URLs included in automated emails:

Sign In Flow

After successful sign in, redirects to:

Custom successAuthPath if provided
Default success page if not provided

Email Links

When provided, these paths are used in automated emails:

verifyAuthPath: Used in verification emails (signup and resend)
updatePasswordPath: Used in password reset emails

Path Configuration Examples

<!-- Signup with custom verification URL -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
    action="signup"
    verifyAuthPath="https://your-site.com/verify"
    // The verification email will include: https://your-site.com/verify?token=ABC123
></script>

<!-- Password reset with custom update URL -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
    action="reset"
    updatePasswordPath="https://your-site.com/update-password"
    // The reset email will include: https://your-site.com/update-password?token=XYZ789
></script>

<!-- Complete authentication flow example -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
    action="verify"
    signinAuthPath="https://your-site.com/login"
    verifyAuthPath="https://your-site.com/verify"
></script>

The verifyAuthPath and updatePasswordPath are particularly important as they determine the URLs in authentication emails:

Verification emails (signup & resend) will use verifyAuthPath + verification token
Password reset emails will use updatePasswordPath + reset token

Theme Examples

<!-- Light theme (default) -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
    action="signin"
></script>

<!-- Dark theme -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
    action="signin"
    theme="dark"
></script>

<!-- Custom styling (disable default styles) -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
    action="signin"
    disable-styles="true"
></script>

Event Handling

// Success events
widget.on('widget:success', (data) => {
  console.log('Authentication successful:', data);
  // Tokens are automatically stored in localStorage:
  // - authiqa_token: JWT access token
  // - authiqa_token_expiration: Token expiration
  // - authiqa_parent_jwt_secret: Parent JWT secret (for child accounts)
});

// Error events  
widget.on('widget:error', (error) => {
  console.error('Authentication failed:', error);
});

// Verification events
widget.on('verify:success', () => {
  console.log('Email verification successful');
});

HTML Examples for Different Actions

<div id="authiqa"></div>
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
    action="signin"
    data-messages='{
        "signinSuccess": "Welcome back! Redirecting you to dashboard...",
        "signinLoading": "Authenticating your credentials..."
    }'
></script>

React Package

For React applications, we provide a dedicated React wrapper package that simplifies integration and provides a more React-friendly API.

Installation

npm install authiqa-react
# or
yarn add authiqa-react

Include the Authiqa Widget script in your HTML (typically in index.html):

<script defer src="https://widget.authiqa.com"></script>

Basic Usage

import { AuthiqaWidget } from 'authiqa-react';

function App() {
  const handleSuccess = (data) => {
    console.log('Authentication successful:', data);
    // Redirect or update state based on successful authentication
  };

  const handleError = (error) => {
    console.error('Authentication failed:', error);
    // Handle authentication errors
  };

  return (
    <div className="app">
      <h1>My Application</h1>
      <AuthiqaWidget 
        publicKey="YOUR_public_KEY"
        action="signin"
        onSuccess={handleSuccess}
        onError={handleError}
      />
    </div>
  );
}

export default App;

Critical Vite Configuration

⚠️ Important: For Vite applications, include this specific configuration in vite.config.js:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    exclude: ['authiqa-react'],
  },
  build: {
    commonjsOptions: {
      include: [/authiqa-react/, /node_modules/],
    },
  },
});

This configuration is required for the Authiqa widget to initialize properly in Vite applications. Without it, the widget may not load or function correctly.

Props Reference

Prop	Type	Required	Default	Description
`publicKey`	string	Yes	-	Your Authiqa public key
`action`	string	No	”signin”	Authentication action (“signin”, “signup”, “reset”, “verify”, “update”, “resend”)
`theme`	string	No	”light”	Widget theme (“light”, “dark”)
`mode`	string	No	”popup”	Display mode (“popup”, “inline”)
`container`	string	Yes	”authiqa-react-container”	Container ID
`onSuccess`	function	No	-	Callback when authentication succeeds
`onError`	function	No	-	Callback when authentication fails
`customization`	object	No	-	Custom styling options (colors, typography, layout)
`termsAndConditions`	string	No	-	URL to terms and conditions
`privacy`	string	No	-	URL to privacy policy
`notificationSettings`	string	No	-	URL to notification settings
`verifyAuthPath`	string	No	-	Path for email verification
`updatePasswordPath`	string	No	-	Path for password update
`resendAuthPath`	string	No	-	Path for resending verification
`successAuthPath`	string	No	-	Path for success redirect
`signinAuthPath`	string	No	-	Path for sign-in redirect

Customization Options

The customization prop accepts an object with the following structure:

<AuthiqaWidget 
  publicKey="YOUR_public_KEY"
  action="signin"
  customization={{
    pageLayout: {
      backgroundColor: "#f5f5f5",
      formPosition: "center"
    },
    layout: {
      padding: "2rem",
      borderRadius: "10px"
    },
    colors: {
      background: "#ffffff",
      buttonBackground: "#4CAF50",
      buttonText: "#ffffff"
    },
    typography: {
      titleText: {
        signinText: "Welcome Back"
      },
      titleSize: "2rem"
    },
    inputs: {
      emailPlaceholder: "Your email address",
      emailLabel: "Work Email",
      passwordPlaceholder: "Enter your password",
      passwordLabel: "Password",
      height: "48px",
      borderRadius: "8px",
      focusBorderColor: "#4CAF50",
      placeholderAlign: "center"
    },
    buttons: {
      signinText: "Log In"
    }
  }}
/>

Event Handling

import { AuthiqaWidget } from 'authiqa-react';

function AuthPage() {
  const handleSuccess = (data) => {
    console.log('Authentication successful:', data);
    // data contains:
    // - token: JWT access token
    // - user: User information
    // - expiresAt: Token expiration timestamp
    
    // Tokens are automatically stored in localStorage:
    // - authiqa_token: JWT access token
    // - authiqa_token_expiration: Token expiration
  };

  const handleError = (error) => {
    console.error('Authentication failed:', error);
    // error contains:
    // - message: Error message
    // - code: Error code (if available)
  };

  return (
    <AuthiqaWidget 
      publicKey="YOUR_public_KEY"
      action="signin"
      onSuccess={handleSuccess}
      onError={handleError}
    />
  );
}

Authentication Flow Examples

import { AuthiqaWidget } from 'authiqa-react';
import { useNavigate } from 'react-router-dom';

function SignIn() {
  const navigate = useNavigate();
  
  const handleSuccess = () => {
    navigate('/dashboard');
  };
  
  return (
    <div className="signin-page">
      <h1>Sign In</h1>
      <AuthiqaWidget 
        publicKey="YOUR_public_KEY"
        action="signin"
        onSuccess={handleSuccess}
        successAuthPath="/dashboard"
      />
    </div>
  );
}

import { AuthiqaWidget } from 'authiqa-react';

function SignUp() {
  return (
    <div className="signup-page">
      <h1>Create Account</h1>
      <AuthiqaWidget 
        publicKey="YOUR_public_KEY"
        action="signup"
        termsAndConditions="https://your-site.com/terms"
        privacy="https://your-site.com/privacy"
        verifyAuthPath="/verify"
      />
    </div>
  );
}

Framework Integration Examples

Next.js Example

// components/AuthiqaSignIn.js
'use client';

import { AuthiqaWidget } from 'authiqa-react';
import { useRouter } from 'next/navigation';

export default function AuthiqaSignIn() {
  const router = useRouter();
  
  const handleSuccess = () => {
    router.push('/dashboard');
  };
  
  return (
    <AuthiqaWidget 
      publicKey={process.env.NEXT_PUBLIC_AUTHIQA_public_KEY}
      action="signin"
      onSuccess={handleSuccess}
    />
  );
}

React Router Example

import { Routes, Route, Navigate } from 'react-router-dom';
import { AuthiqaWidget } from 'authiqa-react';

// Authentication guard component
function RequireAuth({ children }) {
  const isAuthenticated = localStorage.getItem('authiqa_token') !== null;
  
  if (!isAuthenticated) {
    return <Navigate to="/login" replace />;
  }
  
  return children;
}

function App() {
  return (
    <Routes>
      <Route path="/login" element={
        <AuthiqaWidget 
          publicKey="YOUR_public_KEY"
          action="signin"
          successAuthPath="/dashboard"
        />
      } />
      <Route path="/signup" element={
        <AuthiqaWidget 
          publicKey="YOUR_public_KEY"
          action="signup"
          verifyAuthPath="/verify"
        />
      } />
      <Route path="/dashboard" element={
        <RequireAuth>
          <Dashboard />
        </RequireAuth>
      } />
    </Routes>
  );
}

Google SSO in React

The React wrapper automatically supports Google SSO when it’s enabled for your organization. No additional configuration is needed:

<AuthiqaWidget
  publicKey="YOUR_PUBLIC_KEY"
  action="signin"
  onSuccess={handleSuccess}
  onError={handleError}
/>
// Google SSO button will automatically appear if enabled

Troubleshooting

Widget not loading: Ensure the script is included in your HTML and the container element exists
Vite configuration issues: Make sure to use the exact configuration provided in the Vite Configuration section
Event handlers not firing: Check that event names match expected values (onSuccess, onError)
Styling conflicts: Use the customization prop to override default styles or apply CSS targeting the widget container
Google SSO not appearing: Verify that Google SSO is enabled for your organization in the Authiqa dashboard

Password Expiry Handling

The widget includes built-in support for password expiry management. By default, passwords expire after 90 days to maintain security best practices.

Expired Passwords

When a password has expired (90+ days old):

User is redirected to the password reset page
A warning message is displayed
User must update their password to continue

Expiring Soon

When a password will expire soon:

Warning message shows days until expiry
For urgent warnings (≤3 days), message displays for 3 seconds
For less urgent warnings (4-14 days), user can proceed immediately

This feature helps maintain security compliance by ensuring users update their passwords regularly. The 90-day password rotation policy follows industry security standards and helps protect user accounts from unauthorized access. The expiry warning thresholds are:

Critical: 3 days or less (enforced delay before proceeding)
Warning: 4-14 days (informational only)
No warning: 15-89 days remaining

Password expiry is managed server-side. The widget simply responds to the expiry status returned by the authentication API. The 90-day expiry period starts from the date when the password was last changed.

Global Configuration

The Authiqa Widget supports a centralized configuration approach that allows you to define styling and messaging options once and apply them across all authentication forms on your website.

How It Works

Create a JavaScript file (e.g., global-config.js) with your customization settings
Include this file in your HTML pages before the Authiqa widget script
The widget will automatically apply these settings to all forms

<head>
    <!-- Include the global config first -->
    <script src="/path/to/global-config.js"></script>
    <script 
        src="https://widget.authiqa.com" 
        defer 
        data-public-key="YOUR_public_KEY" 
        action="signin"
    ></script>
</head>

The global configuration file can have any name you choose - it doesn’t have to be named “global-config.js”. What matters is that it defines the window.AuthiqaGlobalConfig object and is loaded before the widget script.

Global Configuration Structure

The global configuration uses a window.AuthiqaGlobalConfig object with two main sections:

customization: Contains all styling and layout options
messages: Contains custom success and loading messages

// Global configuration for Authiqa Widget
window.AuthiqaGlobalConfig = {
    customization: {
        // Layout, colors, typography, etc.
    },
    messages: {
        // Custom success and loading messages
    }
};

Available Global Customization Options

The global configuration supports all the same customization options available through the data-customization attribute, including:

Layout and Colors

customization: {
    // Layout
    layout: {
        padding: "1.5rem",
        borderRadius: "8px",
        maxWidth: "400px"
    },
    
    // Colors
    colors: {
        background: "#27272a",
        buttonBackground: "#10D5C6",
        buttonText: "#1F2025",
        inputBackground: "#212125",
        inputText: "#ffffff",
        inputPlaceholder: "#71717a",
        borderColor: "#3f3f46",
        inputFocusBorderColor: "#10D5C6",
        inputFocusBoxShadow: "0 0 0 2px rgba(16, 213, 198, 0.25)",
        buttonHoverBackground: "#0fbfb1"
    },
    
    // Page Layout
    pageLayout: {
        backgroundColor: "#212125"
    }
}

Typography and Buttons

customization: {
    // Typography
    typography: {
        titleText: {
            signinText: "Sign In",
            signupText: "Get Started",
            resetText: "Forgotten Password?",
            updateText: "Update Password",
            verifyText: "Verify Email",
            resendText: "Resend Confirmation Email"
        },
        subtitleText: {
            signinText: "Welcome back to your account",
            signupText: "Start Authenticating users in minutes",
            resetText: "We'll send you a reset link",
            updateText: "Create a new secure password",
            resendText: "Didn't receive the email?"
        },
        titleSize: "1.9rem",
        titleColor: "#10D5C6",
        titleAlignment: "left",
        titleWeight: "800",
        titleLineHeight: "1.2",
        fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
        termsText: {
            agreePrefix: "I agree with the",
            andConnector: "and",
            defaultPrefix: "default",
            linkText: {
                terms: "Terms of Service",
                privacy: "Privacy Policy",
                notifications: "Notification Settings"
            },
            textColor: "#ffffff",
            linkColor: "#10D5C6"
        }
    },
    
    // Buttons
    buttons: {
        height: "2.5rem",
        borderRadius: "4px"
    }
}

Advanced CSS

customization: {
    // Advanced CSS (custom CSS that will be injected)
    advancedCSS: `
        /* Add subtitle after h1 */
        .authiqa-container h1:after {
            content: attr(data-subtitle);
            display: block;
            color: #ffffff !important;
            font-size: 0.7rem !important;
            font-weight: 400 !important;
            margin-top: 0.4rem !important;
            line-height: 0.6 !important;
            margin-bottom: 1rem !important;
        }
        
        /* Input focus state */
        .authiqa-container input:focus {
            border-color: #10D5C6 !important;
            box-shadow: 0 0 0 2px rgba(16, 213, 198, 0.25) !important;
        }
        
        /* Button hover state */
        .authiqa-container button[type="submit"]:hover {
            background-color: #0fbfb1 !important;
        }
        
        /* Title alignment */
        .authiqa-container h1 {
            text-align: left !important;
            font-weight: 800 !important;
            line-height: 1.2 !important;
        }
    `
}

Global Messages

The global configuration also supports custom messages for different authentication actions:

messages: {
    signupSuccess: "Account created successfully! Please check your email for verification.",
    signupLoading: "Creating your account...",
    signinSuccess: "Welcome back! You've successfully signed in.",
    resetSuccess: "Password reset link sent! Please check your email.",
    resetLoading: "Sending password reset link...",
    updateSuccess: "Password updated successfully! You can now sign in with your new password.",
    updateLoading: "Updating your password...",
    resendSuccess: "Confirmation email sent! Please check your inbox.",
    resendLoading: "Sending confirmation email..."
}

Overriding Global Settings

You can override global settings on a per-page basis by providing customization attributes directly in the widget script tag:

<script
    src="https://widget.authiqa.com"
    defer
    data-public-key="YOUR_public_KEY"
    data-customization='{
        "colors": {
            "buttonBackground": "#FF5500"
        }
    }'
></script>

Page-specific settings will take precedence over global settings for the same properties.

The global configuration is particularly useful for maintaining consistent branding across all authentication forms on your website. It reduces duplication and makes it easier to update the styling of all forms at once.

Complete Global Configuration Example

Here’s a complete example of a global configuration file:

// global-config.js
window.AuthiqaGlobalConfig = {
    customization: {
        // Layout
        layout: {
            padding: "1.5rem",
            borderRadius: "8px",
            maxWidth: "400px"
        },
        
        // Colors
        colors: {
            background: "#27272a",
            buttonBackground: "#10D5C6",
            buttonText: "#1F2025",
            inputBackground: "#212125",
            inputText: "#ffffff",
            inputPlaceholder: "#71717a",
            borderColor: "#3f3f46",
            inputFocusBorderColor: "#10D5C6",
            inputFocusBoxShadow: "0 0 0 2px rgba(16, 213, 198, 0.25)",
            buttonHoverBackground: "#0fbfb1"
        },
        
        // Typography
        typography: {
            titleText: {
                signinText: "Sign In",
                signupText: "Get Started",
                resetText: "Forgotten Password?",
                updateText: "Update Password",
                verifyText: "Verify Email",
                resendText: "Resend Confirmation Email"
            },
            subtitleText: {
                signinText: "Welcome back to your account",
                signupText: "Start Authenticating users in minutes",
                resetText: "We'll send you a reset link",
                updateText: "Create a new secure password",
                resendText: "Didn't receive the email?"
            },
            titleSize: "1.9rem",
            titleColor: "#10D5C6",
            titleAlignment: "left",
            titleWeight: "800",
            titleLineHeight: "1.2",
            fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
            termsText: {
                agreePrefix: "I agree with the",
                andConnector: "and",
                defaultPrefix: "default",
                linkText: {
                    terms: "Terms of Service",
                    privacy: "Privacy Policy",
                    notifications: "Notification Settings"
                },
                textColor: "#ffffff",
                linkColor: "#10D5C6"
            }
        },

        // Input Fields
        inputs: {
            emailPlaceholder: "Your work email",
            passwordPlaceholder: "Create a strong password",
            usernamePlaceholder: "Choose a username",
            confirmPasswordPlaceholder: "Re-enter your password",
            emailLabel: "Email Address",
            passwordLabel: "Password",
            usernameLabel: "Username",
            confirmPasswordLabel: "Confirm Password",
            height: "48px",
            borderRadius: "8px",
            focusBorderColor: "#10D5C6",
            focusBoxShadow: "0 0 0 2px rgba(16, 213, 198, 0.25)",
            placeholderAlign: "left"
        },

        // Buttons
        buttons: {
            height: "2.5rem",
            borderRadius: "4px"
        },
        
        // Page Layout
        pageLayout: {
            backgroundColor: "#212125"
        },
        
        // Advanced CSS
        advancedCSS: `
            /* Custom CSS here */
        `
    },
    
    // Custom messages
    messages: {
        signupSuccess: "Account created successfully! Please check your email for verification.",
        signupLoading: "Creating your account...",
        signinSuccess: "Welcome back! You've successfully signed in.",
        resetSuccess: "Password reset link sent! Please check your email.",
        resetLoading: "Sending password reset link...",
        updateSuccess: "Password updated successfully! You can now sign in with your new password.",
        updateLoading: "Updating your password...",
        resendSuccess: "Confirmation email sent! Please check your inbox.",
        resendLoading: "Sending confirmation email..."
    }
};

The widget now supports hash-based navigation, allowing users to switch between different authentication forms by changing the URL hash.

<div id="authiqa"></div>

<!-- Include the Authiqa widget -->
<script 
    defer
    src="https://widget.authiqa.com"
    data-public-key="YOUR_public_KEY"
></script>

<!-- Include the hash navigation script -->
<script src="https://widget.authiqa.com/latest/hash-navigation.js" defer></script>

<!-- Optional navigation links -->
<div class="auth-links">
    <a href="#signin">Sign In</a>
    <a href="#signup">Sign Up</a>
    <a href="#reset">Reset Password</a>
</div>

The hash navigation follows these priority rules:

If a URL hash is present (e.g., #signin), it will show the corresponding form
If no hash is present, it will use the action attribute from the script tag
If neither is available, it will default to the signin form

This allows you to set a default form using the action attribute while still enabling hash-based navigation.

Supported Hash Values

The hash navigation script supports the following hash values:

Hash	Form Displayed
`#signin`	Sign In form
`#signup`	Sign Up form
`#verify`	Email Verification form
`#reset`	Password Reset form
`#update`	Password Update form
`#resend`	Resend Confirmation form

The hash navigation script automatically reads all configuration from the main widget script tag, including:

data-public-key: Your public key
theme: Widget theme setting
All path attributes (verifyAuthPath, updatePasswordPath, etc.)
enable-google-one-tap: Google One Tap configuration

When the page loads or the hash changes, the script:

Extracts the action from the URL hash (e.g., #signin becomes signin)
Checks if it’s a valid authentication action
Creates or retrieves the widget instance with all configuration from the script tag
Shows the appropriate form based on the hash or falls back to the original action

// Example of how hash navigation works internally
function handleHashChange() {
  const hash = window.location.hash.substring(1); // Remove the # character
  const validActions = ['signin', 'signup', 'verify', 'reset', 'update', 'resend'];
  
  if (validActions.includes(hash)) {
    // Show the form corresponding to the hash
    widget.show(hash);
  } else if (hash === '') {
    // No hash or empty hash, respect the original action attribute
    widget.show(originalAction);
  }
}

#### URL Examples

The hash-based navigation works with any URL structure:

- `https://example.com#signin`
- `https://example.com/auth#signup`
- `https://example.com/account/settings?user=123#reset`

<Note>
The hash navigation script must be included after the main widget script. It automatically uses the same configuration attributes (public key, theme, custom paths, etc.) from the main widget script.
</Note>

#### React Integration

For React applications, you can use the hash navigation with the React wrapper:

```jsx
import { AuthiqaWidget } from 'authiqa-react';

function App() {
  // Include the hash navigation script in your HTML
  // <script src="https://widget.authiqa.com/latest/hash-navigation.js" defer></script>
  
  return (
    <div className="app">
      <AuthiqaWidget 
        publicKey="YOUR_public_KEY"
        // No need to specify action - it will be determined by the hash
      />
      
      {/* Optional navigation links */}
      <div className="auth-links">
        <a href="#signin">Sign In</a>
        <a href="#signup">Sign Up</a>
        <a href="#reset">Reset Password</a>
      </div>
    </div>
  );
}

Domain Validation

For security purposes, the widget includes domain validation that restricts where it can be used:

By default, the widget only works on domains configured in your organization settings
For development and testing, domain restriction can be disabled through the API
When domain restriction is enabled, the widget will show an unauthorized error if used on non-approved domains

How Domain Validation Works

When the widget initializes, it:

Fetches your organization details from the Authiqa API
Checks if domain restriction is enabled (enabled by default)
If enabled, compares the current domain with your organization’s authorized domains
If the domain is not authorized, displays an “Unauthorized Domain” error message

The validation allows the widget to work on:

Your exact organization domain
Any subdomain of your organization domain
Authiqa domains (for testing in the Authiqa dashboard)

Configuring Domain Restriction

You can check and update domain restriction settings through the Organization API:

# Check domain restriction status
curl -X GET https://api.authiqa.com/organizations/{organization_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Disable domain restriction for development
curl -X PUT https://api.authiqa.com/organizations/{organization_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domainRestrictionEnabled": false
  }'

The development mode attribute should only be used for local testing and should not be included in production code. For production environments, properly configure your organization’s authorized domains.

Getting Started

Authentication

Features

​Widget Integration

​Configuration Options

​Required Attributes

​Optional Attributes

​URL-Based Action Detection

​Direct CSS Styling

​CSS Class Reference

​Combined Example with Custom CSS and URL-Based Action

​Advanced Customization

​Page and Form Layout

​Colors and Typography

​Input Fields and Buttons

​Input Field Customization Options

​Complete Customization Example

​Presets

​Apply a preset (script tag)

​Apply a preset (programmatically)

​Customizing on top of a preset

​Preset summaries

​GitHub SSO Integration

​Quick Setup Checklist

​GitHub SSO Features

GitHub Sign-In Button

Unified OAuth Callback

​How GitHub SSO Works

​GitHub OAuth App Setup Guide

​Step 1: Create a GitHub OAuth App

​Step 2: Get Your Credentials

​Step 3: Configure Authiqa Organization

​Configuration Requirements

​Testing Your GitHub SSO Setup

​Local Development

​Verification Steps

​Common GitHub SSO Issues

GitHub Button Not Appearing

OAuth Callback Errors

​GitHub SSO Example

​Notes on GitHub Flow

​Security Best Practices for GitHub SSO

​Troubleshooting Tips

​Coexistence with Google SSO

​Example: Sign In page with both providers

​Example: Sign Up page

​Redirect Behavior

​Rate Limiting and State Cleanup

​Configuration Summary (GitHub)

​Google SSO Integration

​Quick Setup Checklist

​Google SSO Features

Google Sign-In Button

Google One Tap

​How Google SSO Works

​Google SSO Setup Guide

​Step 1: Create Google OAuth Credentials

​Step 2: Configure Authorized URLs

​Step 3: Get Your Credentials

​Step 4: Configure Authiqa Organization

​Configuration Requirements

​Testing Your Google SSO Setup

​Local Development Setup

​Verification Steps

​Common Google SSO Issues

Google Button Not Appearing

Authentication Errors

​Google SSO Example

​Google One Tap Configuration

​Google One Tap Behavior

​Controlling Google One Tap

​Google One Tap vs. Google Sign-In Button

​Required Google Console Settings Summary

​Google Authentication Flow

​Error Handling

​Google SSO Security Best Practices

Domain Security

Credential Management

​Custom Messages

​Message Behavior

Widget Integration

Configuration Options

Required Attributes

Optional Attributes

URL-Based Action Detection

Direct CSS Styling

CSS Class Reference

Combined Example with Custom CSS and URL-Based Action

Advanced Customization

Page and Form Layout

Colors and Typography

Input Fields and Buttons

Input Field Customization Options

Complete Customization Example

Presets

Apply a preset (script tag)

Apply a preset (programmatically)

Customizing on top of a preset

Preset summaries

GitHub SSO Integration

Quick Setup Checklist

GitHub SSO Features

How GitHub SSO Works

GitHub OAuth App Setup Guide

Step 1: Create a GitHub OAuth App

Step 2: Get Your Credentials

Step 3: Configure Authiqa Organization

Configuration Requirements

Testing Your GitHub SSO Setup

Local Development

Verification Steps

Common GitHub SSO Issues

GitHub SSO Example

Notes on GitHub Flow

Security Best Practices for GitHub SSO

Troubleshooting Tips

Coexistence with Google SSO

Example: Sign In page with both providers

Example: Sign Up page

Redirect Behavior

Rate Limiting and State Cleanup

Configuration Summary (GitHub)

Google SSO Integration

Quick Setup Checklist

Google SSO Features

How Google SSO Works

Google SSO Setup Guide

Step 1: Create Google OAuth Credentials

Step 2: Configure Authorized URLs

Step 3: Get Your Credentials

Step 4: Configure Authiqa Organization

Configuration Requirements

Testing Your Google SSO Setup

Local Development Setup

Verification Steps

Common Google SSO Issues

Google SSO Example

Google One Tap Configuration

Google One Tap Behavior

Controlling Google One Tap

Google One Tap vs. Google Sign-In Button

Required Google Console Settings Summary

Google Authentication Flow

Error Handling

Google SSO Security Best Practices

Custom Messages

Message Behavior

Authentication Paths

Path Configuration Examples

Theme Examples

Event Handling

HTML Examples for Different Actions

React Package

Installation

Basic Usage

Critical Vite Configuration

Props Reference

Customization Options

Event Handling

Authentication Flow Examples