Integration Guides

User onboarding & account lifecycle

View as Markdown

This guide explains how users are created, authenticated, and managed when integrating with AISquare.

Overview

AISquare is designed to support per-user identity and personalization.

Instead of using a shared account, each user should have their own AISquare account created programmatically.

Recommended approach — Use API-based user registration with per-user API keys.

Your platform handles user onboarding, while AISquare handles:

  • Identity
  • Activity tracking
  • Personalization
  • Metrics

User lifecycle

A typical user lifecycle looks like this:

User signs up on your platform
       ↓
Backend registers user in AISquare
       ↓
AISquare generates API key
       ↓
Backend stores API key
       ↓
User interacts with AISquare-powered features

Step 1: Register user

When a new user is created on your platform:

  • Call AISquare’s user registration API
  • Create a corresponding AISquare user
  • Receive an API key for that user

Important notes:

  • Registration is handled programmatically
  • Users do not need to sign up manually
  • Users may receive an automated welcome email

Step 2: Store credentials

After registration:

  • Store the user’s API key securely in your backend
  • Associate it with your internal user ID

Example:

1{
2  "user_id": "user_123",
3  "aisquare_api_key": "api_key_xyz"
4}

Step 3: Authenticate requests

When your user interacts with your app:

  • Your backend retrieves their API key
  • Uses it to call AISquare APIs on their behalf
Authorization: Bearer <api_key>

Step 4: Enable personalization

Because each user has a unique account, AISquare can track:

  • Activity history
  • Engagement patterns
  • Performance metrics

This enables:

  • Personalized content
  • Adaptive difficulty
  • Leaderboards
  • User-specific analytics

Alternative: token-based flow

Instead of using API keys directly, you can use tokens.

Step 1: Login using API key

Send the API key to the login endpoint.

Step 2: Receive tokens

AISquare returns:

  • Access token
  • Refresh token

Token expiry

TokenExpiry
Access token7 days
Refresh token30 days

Step 3: Use access token

Authorization: Bearer <access_token>

Step 4: Refresh token

When the access token expires:

  • Use the refresh token
  • Generate a new access token

Mapping users between systems

You should maintain a mapping between:

  • Your platform user ID
  • AISquare user

Example:

your_user_id → aisquare_user_id / api_key

This ensures consistent identity across systems.

Why not use a shared account

Using a single AISquare account for all users leads to:

  • Mixed activity data
  • No personalization
  • Inaccurate metrics
  • Broken leaderboards

Benefits of per-user accounts

With individual user accounts:

  • Accurate activity tracking
  • Personalized recommendations
  • Meaningful performance metrics
  • Scalable user management

Best practices

Register users lazily

Only create AISquare users when needed.

Store API keys securely

  • Never expose API keys in frontend
  • Use encrypted storage

Handle duplicate users

Ensure users are not registered multiple times.

Monitor onboarding flow

Track failures in registration and retries.

Putting it together

  1. User signs up on your platform
  2. Backend registers user in AISquare
  3. API key is stored securely
  4. Backend uses API key for requests
  5. AISquare tracks user activity