Skip to main content

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.

Env naming

Chat login uses AION_CHAT_* variables (AION_CHAT_PASSWORD_AUTH, AION_CHAT_AUTH_SECRET, AION_SETUP_CHAT_IDENTIFIER, AION_SETUP_CHAT_PASSWORD).

Admin panel — always protected

Regardless of AION_CHAT_PASSWORD_AUTH, /admin is always protected via require_admin_role. See admin-ui.md.

Current behavior​

  • API POST /chat: user_id in body and/or X-AION-User-Id (sanitized in src/identity.py), propagated to agent, MCP, and profile memory.
  • USER.md: via src/memory/memory_files.py and /admin/profile-memory/* (SOUL/MEMORY deprecated — see soul-memory-user).
  • chat-ui (primary client): POST /auth/login → HMAC token signed with AION_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​

  1. Set AION_CHAT_AUTH_SECRET (e.g. openssl rand -hex 32).
  2. Set AION_CHAT_PASSWORD_AUTH=1 to require login on chat-ui.
  3. Create users in the users table:
    • 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
  4. identifier + AION_DEFAULT_TENANT_ID scope login; the same identifier is used as user_id toward USER.md and /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():

  1. Authenticated Chat Session: If AION_CHAT_PASSWORD_AUTH is enabled and a valid Bearer token is provided via the Authorization header or query parameters (common in EventSource/SSE), the user identifier from the token payload takes absolute precedence.
  2. Open mode or trusted BFF: only when the caller is anonymous (AION_CHAT_PASSWORD_AUTH=0) or presents X-AION-Chat-Ui-Secret (server-to-server), the user comes from:
    • The user_id provided inside the JSON request body.
    • The X-AION-User-Id request header (sanitized in src/identity.py).
  3. API key: the key acts as its owner (api_keys.user_id): user_id is 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 the admin role. A presented key is validated even when AION_CHAT_PASSWORD_AUTH=0. See API keys.
  4. 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=1 requires an authenticated session token with the admin role. 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=0 allows administrative access without authentication checks (for local debugging/testing only).

Principles​

ConceptRole
IdentityHuman user (email, OIDC subject, corporate username).
user_id AIONStable string from identity (sanitize_user_id), used for USER.md and API headers.
session_idConversation / sandbox workspace; separate from identity.
Agent profileUser-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.