POST
/
auth
/
google
{
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzAyN...",
  "parentPublicKey": "APK_1234567890abcdef_1234567890"
}

​
Overview

This endpoint allows child 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.

​
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

​
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

1

Google OAuth

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

Token Verification

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

Parent Validation

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

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
5

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": "user@gmail.com",
    "username": "user_gmail_com",
    "publicKey": "APK_abc123def456_1234567890"
  }
}
​
200: Success - Existing User
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "userID": "USR_existing_67890",
    "email": "user@gmail.com",
    "username": "existinguser",
    "publicKey": "APK_def456ghi789_0987654321"
  }
}
​
400: Invalid Token
{
  "message": "Invalid Google token."
}
​
400: Email Not Verified
{
  "message": "Email not verified by Google."
}

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