# Integration patterns (/docs/guides/integration-patterns)

AISquare is a backend service layer. Your application calls it through your own
backend, which keeps your credentials safe and gives you a place to add caching,
business logic, and personalization. This page walks the three integration
shapes and helps you choose one.

Most integrations follow the same spine:

```text
Frontend  ->  Your backend  ->  AISquare API
```

Your backend sits between your application and AISquare. The patterns below are
variations on where that backend lives and what it does.

## Pattern 1: Frontend and backend (recommended) [#pattern-1-frontend-and-backend-recommended]

The common case. A client talks to your backend, and your backend talks to
AISquare.

```text
Client (web or mobile)
   |
Your backend
   |
AISquare API
```

How a request flows:

1. The user does something in your app.
2. Your backend calls the AISquare API.
3. Your backend processes the response and applies any business logic.
4. The frontend renders the result.

This pattern keeps API keys on the server, lets you add caching and
transformations, and is where per-user personalization lives. Use it for content
feeds, recommendations, and dashboards.

## Pattern 2: Server to server [#pattern-2-server-to-server]

No frontend in the loop. Your backend calls AISquare as part of an internal
workflow.

```text
Your backend  ->  AISquare API
```

The call runs inside a service or a scheduled job rather than in response to a
user action. Use it for syncing user data, generating reports, and running
analytics jobs.

## Pattern 3: Platform embedding [#pattern-3-platform-embedding]

AISquare powers features inside another product, such as a learning or gaming
platform. Your platform owns the users and authentication, and calls AISquare on
their behalf.

```text
User  ->  Your platform  ->  AISquare API
```

Here AISquare acts as a data and intelligence layer. Your platform manages
users, handles authentication, and maps your own user IDs to AISquare users. See
[User onboarding](/docs/guides/user-onboarding) for how to register users and
keep that mapping.

<Callout type="info" title="Map your users">
  When you embed AISquare, register each of your users through the API and store
  their key against your own user ID. A shared account merges everyone's
  activity and breaks personalization.
</Callout>

## Choosing a pattern [#choosing-a-pattern]

| Use case          | Recommended pattern  |
| ----------------- | -------------------- |
| Web or mobile app | Frontend and backend |
| Internal services | Server to server     |
| Partner platform  | Platform embedding   |

## Best practices [#best-practices]

Whichever pattern you pick, the same rules apply.

* **Keep credentials on the backend.** Never call AISquare from the frontend
  with a workspace key, and never ship a key in client-side code. See
  [Authentication](/docs/getting-started/authentication).
* **Handle errors gracefully.** Retry transient failures, refresh expired
  tokens, and validate inputs before sending a request. See
  [Errors](/docs/reference/errors).
* **Page through large results.** Do not fetch everything at once. Use the
  shared list parameters in [Search and
  filtering](/docs/guides/search-and-filtering).

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

A typical integration, end to end:

1. The user opens your app.
2. Your backend authenticates the user.
3. Your backend fetches AISquare data.
4. The frontend renders the content.
5. The user interacts, and your backend records or acts on it.

## Next steps [#next-steps]

<Cards>
  <Card title="Authentication" href="/docs/getting-started/authentication" description="Set up workspace API keys and authenticate requests." />

  <Card title="User onboarding" href="/docs/guides/user-onboarding" description="Register users programmatically and manage their lifecycle." />

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

  <Card title="Permissions" href="/docs/guides/permissions" description="How visibility and roles control access to content." />
</Cards>