Identity, users, and chat authentication
Every conversation in AION belongs to a user, so the agent can keep each person's chats, preferences and memory separate. This page explains how AION identifies the user (open mode vs. password login), how roles such as admin work and where users are stored. It is for administrators and IT staff who set up login; developers will find the API and database details further down.
Operational guide for linking real users (tenant / organization), agent profiles, and USER preferences (SOUL/MEMORY deprecated — see soul-memory-user), with authenticated chat-ui and conversation tracking.
Chat login uses AION_CHAT_* variables (AION_CHAT_PASSWORD_AUTH, AION_CHAT_AUTH_SECRET, AION_SETUP_CHAT_IDENTIFIER, AION_SETUP_CHAT_PASSWORD).
Regardless of AION_CHAT_PASSWORD_AUTH, /admin is always protected via require_admin_role. See admin-ui.md.
Current behavior
- API
POST /chat:user_idin body and/orX-AION-User-Id(sanitized insrc/identity.py), propagated to agent, MCP, and profile memory. - USER.md: via
src/memory/memory_files.pyand/admin/profile-memory/*(SOUL/MEMORY deprecated — see soul-memory-user). - chat-ui (primary client):
POST /auth/login→ HMAC token signed withAION_CHAT_AUTH_SECRET(src/chat_auth.py,src/api/auth_login.py). - Persistence: unified schema in
AION_DB_URL(conversations,messages,steps, …). No separate chat database.
Chat password login
- Set
AION_CHAT_AUTH_SECRET(e.g.openssl rand -hex 32). - Set
AION_CHAT_PASSWORD_AUTH=1to require login on chat-ui. - Create users in the
userstable:- Setup wizard:
scripts/setup-aion-env.sh(prompts to bootstrap the initial user during setup). - Admin UI or
POST /admin/users(password mode only; with SSO active, accounts are created at first SSO sign-in — see SSO migration). The admin sets no password: the user receives an email invite and chooses it on/set-password— see Password setup by email. Users can also recover access with "Forgot password?" on the login page. - Password hash:
python -m src.chat_auth hash
- Setup wizard:
identifier+AION_DEFAULT_TENANT_IDscope login; the same identifier is used asuser_idtowardUSER.mdand/chat.
Non-interactive setup (-y): set AION_SETUP_CHAT_IDENTIFIER and AION_SETUP_CHAT_PASSWORD in .env, or provision via admin API.
With login disabled (AION_CHAT_PASSWORD_AUTH=0), chat endpoints remain open (dev only).
Identity and user_id Resolution Hierarchy
During chat session initiation (e.g. POST /chat/stream), user_id is resolved dynamically based on the current client identity context using _resolve_chat_user_id():
- Authenticated Chat Session: If
AION_CHAT_PASSWORD_AUTHis enabled and a valid Bearer token is provided via theAuthorizationheader or query parameters (common in EventSource/SSE), the user identifier from the token payload takes absolute precedence. - Open mode or trusted BFF: only when the caller is anonymous (
AION_CHAT_PASSWORD_AUTH=0) or presentsX-AION-Chat-Ui-Secret(server-to-server), the user comes from:- The
user_idprovided inside the JSON request body. - The
X-AION-User-Idrequest header (sanitized insrc/identity.py).
- The
- API key: the key acts as its owner (
api_keys.user_id):user_idis the owner's identifier, the same as with the owner's chat token, so the key sees the owner's conversations and allowed profiles. Header and body identities are ignored, and the key never carries theadminrole. A presented key is validated even whenAION_CHAT_PASSWORD_AUTH=0. See API keys. - Default Value: In open mode, if no identification mechanism is provided, the session owner defaults to
"default".
The resolution lives in effective_user_id() (src/api/ownership.py). With a chat token, X-AION-User-Id is ignored.
Conversation Ownership
No one, admins included, can read another user's chats. Every endpoint that touches a conversation, session, step, file, chart, tool ledger, cron target or A2A session calls assert_conversation_access(); a mismatch returns 404. Admin endpoints follow the same rule: /admin/ltm/* and /admin/memory/facts only serve the caller's own user scope, and /admin/diagnostics/file only serves files from smoke-test sessions (smoke*).
All resolved user IDs are sanitized through sanitize_user_id() to guarantee safe directory-friendly pathnames under data/sessions/ and database entries.
Admin Role Protection
Administrative endpoints /admin/* are gated via the require_admin_role FastAPI dependency.
- Default (Grafana-style protection):
AION_ADMIN_PASSWORD_AUTH=1requires an authenticated session token with theadminrole. The server-to-server secret (X-AION-Chat-Ui-Secret) does not grant the admin role, and API keys are rejected on every/admin/*endpoint. - Development Bypass: Setting
AION_ADMIN_PASSWORD_AUTH=0allows administrative access without authentication checks (for local debugging/testing only).
Principles
| Concept | Role |
|---|---|
| Identity | Human user (email, OIDC subject, corporate username). |
user_id AION | Stable string from identity (sanitize_user_id), used for USER.md and API headers. |
session_id | Conversation / sandbox workspace; separate from identity. |
| Agent profile | User-selected profile mapped to profile in /chat. |
Roadmap (enterprise)
- User catalog CRUD and role-based profile ACL.
- OAuth / SSO for chat-ui (replace or complement password auth).
- Multi-tenant filesystem prefixes under
data/sessions/where needed.