Google Authentication

Overview

This endpoint allows users to authenticate using their Google account. The system supports both new user creation and linking existing accounts with Google authentication. Parent organizations can configure their own Google OAuth credentials for custom branding. Credit System: Google OAuth authentication costs 3 credits from the parent account. Child accounts are blocked if parent has insufficient credits, but parent accounts always have access.

API Details

Request Format

idToken

string

required

Google ID token received from Google OAuth flow

parentPublicKey

string

required

Parent organization’s public key for child account creation

{
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzAyN...",
  "parentPublicKey": "APK_1234567890abcdef_1234567890"
}

Try It Out

Test the API by providing your Google ID token and parent public key:

idToken

required

Google ID token from OAuth flow

parentPublicKey

required

Parent organization’s public key

Hide Headers

Content-Type

Code Examples

curl -X POST https://api.authiqa.com/auth/google \
  -H "Content-Type: application/json" \
  -d '{
    "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzAyN...",
    "parentPublicKey": "APK_1234567890abcdef_1234567890"
  }'

Authentication Flow

Google OAuth

User initiates Google sign-in on frontend
Google returns ID token after successful authentication
Frontend sends ID token to this endpoint

Token Verification

Validate Google ID token with Google’s servers
Extract user information (email, Google ID, name)
Verify email is verified by Google

Parent Validation

Validate parent public key format and existence
Check if parent has Google SSO configured
Use parent’s Google OAuth credentials if available

User Resolution

Check if user exists by Google ID
If not found, check if email exists for account linking
Create new user if no existing account found

Token Generation

Generate JWT token for authenticated user
Update user’s last login information
Return authentication response

Response Examples

200: Success - New User

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "userID": "USR_google_12345",
    "email": "[email protected]",
    "username": "user_gmail_com",
    "publicKey": "APK_abc123def456_1234567890"
  }
}

200: Success - Existing User

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "userID": "USR_existing_67890",
    "email": "[email protected]",
    "username": "existinguser",
    "publicKey": "APK_def456ghi789_0987654321"
  }
}

400: Invalid Token

{
  "message": "Invalid Google token."
}

400: Email Not Verified

{
  "message": "Email not verified by Google."
}

Google Developer Setup Guide

Creating a Google OAuth Application

Access Google Cloud Console

Go to Google Cloud Console
Create a new project or select an existing one
Ensure billing is enabled for your project

Enable Google+ API

Navigate to APIs & Services > Library
Search for Google+ API (or Google People API for newer projects)
Click Enable to enable the API for your project

Create OAuth Credentials

Go to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
If prompted, configure the OAuth consent screen first
Select Web application as the application type

Configure Redirect URLs

Add your redirect URLs in Authorized redirect URIs:
- For development: http://localhost:3000/auth/google/callback
- For production: https://yourdomain.com/auth/google/callback
Save the credentials to get your Client ID and Client Secret

Configure Organization Settings

In your parent organization dashboard, navigate to Settings > Authentication
Enter your Google Client ID and Google Client Secret
Save the configuration to enable Google SSO for child accounts

Required Scopes

The following scopes are required for Google authentication:

email - Access to user’s email address
profile - Access to user’s basic profile information
openid - OpenID Connect authentication

Testing Your Setup

Before going live, test your Google OAuth integration:

Use Google’s OAuth 2.0 Playground
Test the complete flow in your development environment
Verify email verification status is returned

Error Codes

400 Bad Request

Invalid input - Request body validation failed
Missing or invalid parentPublicKey - Parent public key required
Invalid parentPublicKey format - Public key format validation failed
Invalid parent public key - Parent account not found
Invalid Google token - Google ID token verification failed
Email not verified by Google - Google account email not verified

500 Internal Server Error

Failed to create or update user - Database operation failed
Failed to generate authentication token - JWT generation failed
Internal Server Error - Unexpected server error

Google OAuth Configuration

Parent Organization Setup

Parent organizations can configure their own Google OAuth credentials:

Custom OAuth

Configure via Update Organization API
Use organization’s Google OAuth app
Custom branding and domain restrictions
Enhanced security and control

Default OAuth

Uses Authiqa’s default Google OAuth
Fallback when organization hasn’t configured
Standard Google authentication flow
Basic functionality available

Required Google OAuth Scopes

openid - OpenID Connect authentication
email - Access to user’s email address
profile - Access to basic profile information

Security Features

Security Validations

Token Verification: Google ID tokens verified with Google’s servers
Email Verification: Only Google-verified emails accepted
Parent Validation: Parent public key format and existence validated
Account Linking: Secure linking of existing accounts with Google
JWT Generation: Secure JWT tokens for authenticated sessions

Account Creation

New Users

Username automatically generated from email
Account type set to “child” under specified parent
Google ID stored for future authentication
Email marked as verified (verified by Google)

Existing Users

Google ID linked to existing account
Maintains existing username and settings
Enables dual authentication (email + Google)
Updates last login information

Notes

This endpoint is specifically designed for child account authentication. Parent accounts should use the standard sign-in endpoint.

The Google ID token must be obtained through a proper OAuth flow and should not be reused. Each authentication request should use a fresh token.

Overview

Authentication APIs

Organization APIs

Billing APIs

Overview

API Details

Request Format

Try It Out

Code Examples

Authentication Flow

Response Examples

Google Developer Setup Guide

Creating a Google OAuth Application

Required Scopes

Testing Your Setup

Error Codes

Google OAuth Configuration

Parent Organization Setup

Custom OAuth

Default OAuth

Required Google OAuth Scopes

Security Features

Security Validations

Account Creation

New Users

Existing Users

Notes

Overview

Authentication APIs

Organization APIs

Billing APIs

​Overview

​API Details

​Request Format

​Try It Out

​Code Examples

​Authentication Flow

​Response Examples

​Google Developer Setup Guide

​Creating a Google OAuth Application

​Required Scopes

​Testing Your Setup

​Error Codes

​Google OAuth Configuration

​Parent Organization Setup

Custom OAuth

Default OAuth

​Required Google OAuth Scopes

​Security Features

Security Validations

​Account Creation

​New Users

​Existing Users

​Notes

Overview

API Details

Request Format

Try It Out

Code Examples

Authentication Flow

Response Examples

Google Developer Setup Guide

Creating a Google OAuth Application

Required Scopes

Testing Your Setup

Error Codes

Google OAuth Configuration

Parent Organization Setup

Required Google OAuth Scopes

Security Features

Account Creation

New Users

Existing Users

Notes