***

title: User onboarding & account lifecycle
description: >-
How users are created, authenticated, and managed when integrating with
AISquare.
---------

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:

```json
{
  "user_id": "user_123",
  "aisquare_api_key": "api_key_xyz"
}
```

***

## 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

| Token         | Expiry  |
| ------------- | ------- |
| Access token  | 7 days  |
| Refresh token | 30 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

***

## Related pages

* [Authentication](/docs/getting-started/authentication) — supported auth methods
* [Token lifecycle & session management](/docs/integration-guides/token-lifecycle-session-management) — manage access and refresh tokens
* [Integration patterns](/docs/integration-guides/integration-patterns) — architecture guidance
* [Activity and personalization](/docs/product/activity-and-personalization) — user activity tracking
* [Permissions and access control](/docs/data-ux-guides/permissions-and-access-control) — roles and access levels