Authentication

AISquare supports multiple authentication methods to fit different integration needs, including frontend, backend, and partner platforms.

Supported authentication methods

You can authenticate with AISquare using one of the following:

• JWT authentication
• API key authentication
• Cookie-based authentication
• OpenID authentication

For most integrations, you will use:

• API keys for server-to-server communication
• JWT tokens for authenticated requests

Recommended approach

For partner platforms and integrations, we strongly recommend:

API-based user registration + per-user API keys

This allows your platform to authenticate users without requiring them to manually manage AISquare accounts.

API-based user registration flow

Instead of using a shared account, each user is registered programmatically.

Step 1: Register user via API

Your backend creates a user in AISquare using the registration API.

• User is created automatically
• An API key is generated
• User receives an AISquare welcome email (current behavior)

Step 2: Store API key

Store the API key securely on your backend.

This key will be used to make requests on behalf of the user.

Step 3: Authenticate requests

Use the API key in requests:

Authorization: Bearer <api_key>

Alternative: token-based authentication

AISquare also supports a login flow that exchanges an API key for tokens.

Step 1: Login

Send the user’s API key to the login endpoint.

Step 2: Receive tokens

You will receive:

• Access token
• Refresh token

Token validity

Step 3: Use access token

Authorization: Bearer <access_token>

Step 4: Refresh token

When the access token expires, use the refresh token to generate a new one.

Cookie-based authentication

For browser-based flows, AISquare supports authentication using cookies.

Once authenticated, requests automatically include the session token via cookies.

Server-to-server authentication

For backend integrations, use:

Authorization: Bearer <jwt_token>

This works with both:

• API keys
• Access tokens

Important: avoid shared accounts

Using a single AISquare account for all users is not recommended.

Why? If all users share one account:

• Activity data is merged
• Personalization is lost
• Leaderboards and metrics become inaccurate

Benefits of per-user authentication

When each user has their own account:

• Personalized metrics (ELO, accuracy, streaks)
• Individual activity tracking
• Leaderboard support
• Adaptive difficulty

This enables richer product experiences without additional backend logic.

Choosing the right approach

Next steps

• Use the Quickstart to make your first authenticated request
• Explore Core Concepts to understand AISquare entities
• Learn about Token lifecycle & session management
• Set up User onboarding & account lifecycle
• Understand Permissions and access control
• Review Errors to handle authentication failures
• Browse the API Reference for endpoint details