# User onboarding (/docs/guides/user-onboarding)

AISquare supports per-user identity and personalization. Instead of one shared
account, give each of your users their own AISquare account, created
programmatically from your backend. Your platform owns sign-up; AISquare owns
identity, activity, personalization, and metrics for each user.

<Callout type="info" title="Recommended approach">
  Register users through the API and hold a per-user API key for each one. Your
  users never sign up with AISquare directly.
</Callout>

## User lifecycle [#user-lifecycle]

A user moves through these stages:

```text
User signs up on your platform
   |
Backend registers the user in AISquare
   |
AISquare returns an API key
   |
Backend stores the key
   |
User interacts with AISquare-powered features
```

## Onboarding a user [#onboarding-a-user]

<Steps>
  <Step>
    ### Register the user [#register-the-user]

    When a new user is created on your platform, call the AISquare registration API
    to create a matching AISquare user. Registration is programmatic, so your users
    do not sign up by hand. They may receive an automated welcome email.
  </Step>

  <Step>
    ### Store the credentials [#store-the-credentials]

    Store the returned API key securely on your backend and associate it with your
    own user ID.

    ```json title="User mapping"
    {
      "user_id": "user_123",
      "aisquare_api_key": "api_key_xyz"
    }
    ```
  </Step>

  <Step>
    ### Authenticate requests [#authenticate-requests]

    When the user acts in your app, your backend retrieves their key and calls
    AISquare on their behalf.

    ```text
    Authorization: Bearer <api_key>
    ```
  </Step>

  <Step>
    ### Personalize [#personalize]

    Because each user has a unique account, AISquare can track their activity,
    engagement, and performance, and use it to drive personalized content, adaptive
    difficulty, leaderboards, and per-user analytics.
  </Step>
</Steps>

## Token-based flow (alternative) [#token-based-flow-alternative]

Instead of sending the API key on every call, you can exchange it for tokens.
Log in with the key, receive an access token and a refresh token, then send the
access token the way you would the key. Refresh it when it expires.

| Token         | Expiry  |
| ------------- | ------- |
| Access token  | 7 days  |
| Refresh token | 30 days |

See [Token lifecycle](/docs/guides/token-lifecycle) for the full flow, including
how to detect expiry and refresh safely.

## Mapping users between systems [#mapping-users-between-systems]

Keep a mapping between your platform user ID and the AISquare user (or their
key) so identity stays consistent across both systems.

```text
your_user_id  ->  aisquare_user_id / api_key
```

## Why not a shared account [#why-not-a-shared-account]

Using one AISquare account for every user merges their data: mixed activity, no
personalization, inaccurate metrics, and broken leaderboards. Per-user accounts
give you accurate activity tracking, personalized recommendations, meaningful
metrics, and user management that scales.

## Best practices [#best-practices]

* **Register lazily.** Create an AISquare user only when you first need one.
* **Store keys securely.** Keep keys in encrypted storage on the backend, never
  in the frontend. See [Authentication](/docs/getting-started/authentication).
* **Avoid duplicates.** Make sure a user is not registered more than once.
* **Monitor the flow.** Track registration failures and retry them.

## Putting it together [#putting-it-together]

1. The user signs up on your platform.
2. Your backend registers the user in AISquare.
3. The key is stored securely.
4. Your backend uses the key for requests.
5. AISquare tracks the user's activity.

## Next steps [#next-steps]

<Cards>
  <Card title="Authentication" href="/docs/getting-started/authentication" description="Supported auth methods and how to keep keys safe." />

  <Card title="Token lifecycle" href="/docs/guides/token-lifecycle" description="Manage access and refresh tokens in production." />

  <Card title="Integration patterns" href="/docs/guides/integration-patterns" description="Where your backend sits in the architecture." />

  <Card title="Permissions" href="/docs/guides/permissions" description="Roles and visibility that govern access." />
</Cards>