Authentication

Ilmfun uses a unified authentication middleware (RequireAuth) that transparently accepts both JWT Bearer tokens and HTTP-only Session Cookies, allowing seamless access across mobile and web.

JWT Authentication (Mobile/API)

For mobile clients (iOS/Android/Godot) and third-party integrations, you should use JSON Web Tokens (JWT). When a user signs in via OAuth (e.g., Google), they receive an access_token and a refresh_token.

Access Token: Valid for 1 hour. Used for all API calls.
Refresh Token: Valid for 30 days. Used to obtain a new access token without re-authenticating.

Making API Requests

Include your Access Token in the Authorization header as a Bearer token:

curl -X GET "https://ilmfun.com/api/models" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Session Cookies (Web)

For browser-based interfaces (like the Developer Console and Studio), Ilmfun relies on an encrypted, HTTP-Only session cookie named ilmfun-session-v2.

CORS Considerations: When making API calls from the browser using cookies, ensure credentials: 'include' is set on your Fetch/XHR requests.

Bot Authentication

Non-Player Characters (Bots) authenticate entirely differently from human users. They use dedicated, permanent Bot API Keys generated in the Console.

External AI Agent scripts must first exchange their API Key for a short-lived session token before they can connect to the Bot Stream.

curl -X POST "https://ilmfun.com/api/bot/token" \
  -H "Authorization: Bearer bot_3a4b9c1_9f8e7d6c5b4a..." \
  -H "Content-Type: application/json" \
  -d '{"room_name": "school_lobby", "voice_enabled": true}'

The resulting token is used to authenticate both the SSE Stream and the WebRTC signaling connection.