Skip to main content

Authentication

Optional single-user login is available in V1 (open source). Full multi-user access — invite codes, multiple accounts, per-user isolation, and the Admin Console — is part of V2, the invite-only governed edition. See V1 vs V2.

Default: no auth (single-user)​

Out of the box, AI Partner runs without authentication — anyone who can reach localhost:3000 has full access. This is fine for local personal use.

For team deployments, production servers, or anywhere the instance is reachable over a network, enable authentication.

Enabling authentication​

# .env
AI_PARTNER_AUTH_ENABLED=true
AI_PARTNER_JWT_SECRET=generate-a-random-64-char-string

After enabling auth and restarting, navigating to the UI redirects to the Login page.

First-time setup (register admin)​

On first access after enabling auth, the registration form appears. The first user to register needs no invite code and automatically becomes the admin:

Create account

Username: _______________
Password: _______________

[Create Account]

Every subsequent user needs a single-use invite code, which the admin generates in Admin Console → Users (optionally with an expiry). There is no open self-registration — membership is invite-only by design.

Logging in​

Username: yourname
Password: ************

[Log In]

Sessions use a JWT delivered via httpOnly cookie (with an Authorization: Bearer header fallback for the SPA and Socket.IO handshake). Tokens expire after 24 hours.

API keys​

For programmatic access (scripts, integrations, CI/CD), use API keys instead of session cookies.

Generate an API key​

Go to Settings → API Keys → + Generate Key:

Name: "CI pipeline"
Permissions: read-only  (or read-write)

[Generate]

Copy the key immediately — it's shown once and never stored in plaintext.

Using an API key​

Pass the key as a Bearer token:

curl -H "Authorization: Bearer aip_xxxxxxxxxxxx" \
  http://localhost:3000/api/autonomous/goal

Or as a query parameter:

curl "http://localhost:3000/api/files?api_key=aip_xxxxxxxxxxxx"

Revoking a key​

Go to Settings → API Keys → click Revoke next to any key. Revocation is immediate.

Password recovery​

If you forget your password:

  1. 1
    Generate a recovery key (before you forget)

    Go to Settings → Security → Generate Recovery Key. Copy and store it somewhere safe — this is a one-time-use code that bypasses authentication.

  2. 2
    Use recovery key to reset

    On the login page, click Forgot password → enter your recovery key → set a new password.

  3. 3
    If no recovery key exists

    Contact your administrator to reset your password.

JWT token refresh​

Access tokens expire after 15 minutes. Refresh tokens expire after 7 days. Refreshes happen automatically in the UI — you won't be logged out mid-session.

For API access, implement token refresh:

# Refresh
POST /api/auth/refresh
Cookie: refresh_token=...

# Response
{ "accessToken": "eyJ..." }

Auth configuration reference​

VariableDefaultDescription
AUTH_ENABLEDfalseEnable/disable authentication
SESSION_SECRETautoSecret for session signing
JWT_SECRETautoSecret for JWT signing
JWT_EXPIRY15mAccess token lifetime
REFRESH_TOKEN_EXPIRY7dRefresh token lifetime
ALLOW_REGISTRATIONfalseAllow users to self-register (true = open, false = invite only)
MAX_LOGIN_ATTEMPTS5Lock account after N failed attempts
LOCKOUT_DURATION_MINUTES15How long a locked account stays locked

Multi-user considerations​

When auth is enabled and multiple users share an instance:

  • Each user has their own conversation history and goals
  • Memory (episodic, biographic, vector) is per-user by default
  • Agent profiles and skills are shared across users
  • Audit log entries are tagged with userId — admins can filter by user
  • The Authority Policy (AUTHORITY.md) is currently shared — per-user authority policies are on the roadmap

Multi-user support is functional but not the primary design target — AI Partner is optimised for single-user personal deployments. For team use, a shared instance works but all users share the same LLM provider keys and workspace configuration.